libraries/3-release-policy.md

-## Rationale
+# This document is not finalized yet
 
 
 
@@ -9,7 +9,8 @@ Changes to the basic libraries, especially the Prelude, can be disruptive, as th
 
 
 
-Changes to basic libraries are planned and implemented so that, at any time, it is possible to write code that works with the latest **three** releases of GHC and base, without resorting to CPP, and without causing warnings even when compiled with `-Wall`. Such code may not necessarily be idiomatic, though.
+Changes to basic libraries are planned and implemented so that, at any time, it is possible to write code that works with the latest **three** releases of GHC and base, without resorting to CPP, and without 
+causing warnings even when compiled with `-Wall`. Such code may not necessarily be idiomatic, though.
 
 
 ## Scope
@@ -23,6 +24,136 @@ The primary scope of this policy is the Prelude, as it affects the largest numbe
 As this is but a guideline, it may be violated if it is impossible to adhere to, or causes major disadvantages.
 
 
+## Comments
+
+
+
+We picked three releases as a good compromise between the wish to rapidly implement new features and the desire of stability and having maintainers do boring technical adjustments not too-frequently. Furthermore it aligns somewhat well with the timelines of downstream packagers, e.g. Linux distributions.
+
+
+## Example
+
+
+
+The [Libraries/Proposals/MonadFail](libraries/proposals/monad-fail) proposal is an example of a transition that adheres to this policy, and serves here as an example of a few of the mechanisms that can be used to achieve this. This is not the only possible way to implement it, nor is the given code the only way to write it in light of the changes (e.g. in case a libraries author actually prefers CPP).
+
+
+
+Please see [Libraries/Proposals/MonadFail](libraries/proposals/monad-fail) for details on that particular proposal; the example here might not be up-to-date in case the MonadFail? transition changes.
+
+
+### pre GHC-8.0
+
+
+
+ 
+Backward-compatible code:
+
+
+```
+instance Monad Foo where
+  ...
+  fail = ...
+
+do Just x <- ...
+   return x
+```
+
+### CHC-8.0
+
+
+
+Changes implemented:
+
+
+- Module `Control.Monad.Fail` with class `MonadFail` and method `fail`, distinct from `Prelude`’s `fail` added.
+- Language extension `-XControl.Monad.Fail` to change desugaring to use that `fail`
+- (Some warnings, off by default, are added)
+
+
+Backward-compatible code as above.
+
+
+### CHC-8.2
+
+
+
+No change, backward-compatible code as above.
+
+
+### CHC-8.4
+
+
+
+Changes implemented:
+
+
+- Warn by default when a `MonadFail` instance is not in scope where do-notation desugars to `fail`.
+
+
+Backward-compatible code:
+
+
+```
+import qualified Control.Monad.Fail as Fail
+
+instance Monad Foo where
+  ...
+  fail = Fail.fail
+
+instance Fail.MonadFail Foo where
+  ...
+  fail = ...
+
+do Just x <- ...
+   return x
+```
+
+### CHC-8.6
+
+
+
+Changes implemented:
+
+
+- `-XMonadFailDesugaring` is the default now
+- Explicit definitions of `Monad.fail` cause warnings now. (**TODO**: Even a canonical `fail = Fail.fail` definition?)
+
+
+ 
+
+
+
+Backward-compatible code (**correct?**)
+
+
+```
+{-# LANGUAGE MonadFailDesugaring #-}
+import qualified Control.Monad.Fail as Fail
+
+instance Fail.MonadFail Foo where
+  ...
+  fail = ...
+
+do Just x <- ...
+   return x
+```
+
+### CHC-8.8
+
+
+
+Changes implemented:
+
+
+- `-XMonadFailDesugaring` is unconditionally true
+- `Monad.fail is removed`
+
+
+ 
+Backward-compatible code: Same as above.
+
+
 ## History