Conventions for Stability field of Cabal packages

Cabal allows for a freeform Stability field:

stability: freeform

The stability level of the package, e.g. alpha开发者_运维知识库, experimental, provisional, stable.

What are the community conventions about these stability values? What is considered experimental and what is provisional? I see only few packages are declared as stable. What kind of stability does it refer to, stability of the exposed API or the ultimate bug-free state of the software?

The field is mostly defunct now, and shouldn't be used. As Max said, it will probably be replaced by something meaningful in the future.

If you're interested in the history, the field originated in a design proposal for the first set of Hierarchical Haskell Libraries. That document describes the original intended meanings for the values.

Currently this field is a very poor guide to the stability of the library, so is mostly ignored. Duncan Coutts (one of the main Cabal and Hackage developers) has said that he eventually plans to replace this field entirely, with something like a social voting system on Hackage.

Personally (and I'm not alone) I just always omit the stability field. Given that it's going to go away, its probably not worth losing any sleep over what to put into it.

The original intended meanings were:

• experimental: the API is unstable. It may change at any time, i.e.: any version number change;
• provisional: the API is moving towards stability. It may be changed at every minor revision, but should provide deprecated versions of features;
• stable: the API is stable. Only additions should be made at minor releases. After changes in the API, deprecated features should be kept for at least one major release.

As the other answers pointed out, the community seems not to be following these guidelines anymore.

As Simon Marlow points out, this is described in a design proposal for the first set of Hierarchical Haskell Libraries. The original link is dead, but you can find a copy in the wayback machine.