libraries/3-release-policy.md

-## Rationale
+# This document is not finalized yet
 
 
 Changes to the basic libraries, especially the Prelude, can be disruptive, as they likely affect a large amount of existing code out there. Especially API breaking changes pose a challenge to library authors: Should they support the new version, the old version, or both, and if both, by what means should they support them (multiple versions, CPP, code that happens to work with either version)? The Core Library Committee decided to support the library authors with this problem, and offer a canonical solution.
@@ -6,7 +6,8 @@ Changes to the basic libraries, especially the Prelude, can be disruptive, as th
 ## Policy
 
 
-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
 
@@ -16,6 +17,100 @@ 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:
+
+```
+instanceMonadFoowhere...
+  fail =...doJust 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:
+
+```
+importqualifiedControl.Monad.Failas Fail
+
+instanceMonadFoowhere...
+  fail =Fail.fail
+
+instanceFail.MonadFailFoowhere...
+  fail =...doJust 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 #-}importqualifiedControl.Monad.Failas Fail
+
+instanceFail.MonadFailFoowhere...
+  fail =...doJust x <-...
+   return x
+```
+
+### CHC-8.8
+
+
+Changes implemented:
+
+- `-XMonadFailDesugaring` is unconditionally true
+- `Monad.fail is removed`
+
+
+ 
+Backward-compatible code: Same as above.
+
 ## History
 
 - 2015-10-13: Edward suggested the policy in a mail to the haskell-core-library committee: [ https://groups.google.com/d/msg/haskell-core-libraries/qXYMfV8JZ6k/tTuFrBMdDgAJ](https://groups.google.com/d/msg/haskell-core-libraries/qXYMfV8JZ6k/tTuFrBMdDgAJ)