Skip to content

Changes

Page history
Edit Libraries/3-Release-Policy authored by Joachim Breitner's avatar Joachim Breitner
Hide whitespace changes
Inline Side-by-side
libraries/3-release-policy.md
View page @ e9417d72
## Rationale
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.
## 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.
## Scope
The primary scope of this policy is the Prelude, as it affects the largest number of library authors. For other modules of base and other basic libraries, it is desirable to follow the guideline, if possible.
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). 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.
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.
<table><tr><th>
Version
</th>
<th>
Changes
</th>
<th>
Backwards-Compatible code
</th></tr>
<tr><th>
pre 8.0
</th>
<th>
–
</th>
<th>```
instanceMonadFoowhere...
fail =...doJust x <-...
return x
```
</th></tr>
<tr><th>
8.0
</th>
<th>- Module `Control.Monad.Fail` with class `MonadFail` and method `fail`, distinct from `Prelude`’s `fail` added.
- Language extension `-XMonadFailDesugaring` to change the desugaring to use that `fail`
- (Some warnings, off by default, are added)
</th>
<th></th></tr>
<tr><th>
8.2
</th> ## Policy
<th>*none*
</th>
<th></th></tr>
<tr><th>
8.4
</th>
<th>- Warn by default when a `MonadFail` instance is not in scope where do-notation desugars to `fail`.
</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.
<th>```
importqualifiedControl.Monad.Failas Fail
instanceMonadFoowhere...
fail =Fail.fail
instanceFail.MonadFailFoowhere... ## Scope
fail =...doJust x <-...
return x
```
</th></tr>
<tr><th>
8.6
</th>
<th>- `-XMonadFailDesugaring` is the default now
- Explicit definitions of `Monad.fail` cause warnings now.
</th> The primary scope of this policy is the Prelude, as it affects the largest number of library authors. For other modules of base and other basic libraries, it is desirable to follow the guideline, if possible.
<th>```
{-# LANGUAGE MonadFailDesugaring #-}importqualifiedControl.Monad.Failas Fail
instanceFail.MonadFailFoowhere...
fail =...doJust x <-...
return x
```
</th></tr>
<tr><th>
8.8
</th> As this is but a guideline, it may be violated if it is impossible to adhere to, or causes major disadvantages.
<th>- `-XMonadFailDesugaring` is unconditionally true
- `Monad.fail is removed`
</th>
<th></th></tr></table>
## History ## 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) - 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)
- 2015-11-05: It was accepted at the committee meeting in November: [Libraries/Meetings/2015-11-05](libraries/meetings/2015-11-05) - 2015-11-05: It was accepted at the committee meeting in November: [Libraries/Meetings/2015-11-05](libraries/meetings/2015-11-05)
- 2015-11-26: Joachim drafted this wiki page. - 2015-11-26: Joachim drafted this wiki page.