Skip to content
Snippets Groups Projects

3 release policy

Last edited by Takenobu Tani

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 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 for details on that particular proposal; the example here might not be up-to-date in case the MonadFail transition changes.

Version Changes Backwards-Compatible code
pre 8.0

–

 
instance Monad Foo where
  ...
  fail = ...

do Just x <- ...
   return x
8.0
  • 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)
8.2 *none*
8.4
  • Warn by default when a MonadFail instance is not in scope where do-notation desugars to fail.
 
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
8.6
  • -XMonadFailDesugaring is the default now
  • Explicit definitions of Monad.fail cause warnings now.
 
{-# LANGUAGE MonadFailDesugaring #-}
import qualified Control.Monad.Fail as Fail

instance Fail.MonadFail Foo where
  ...
  fail = ...

do Just x <- ...
   return x
8.8
  • -XMonadFailDesugaring is unconditionally true
  • Monad.fail is removed

History