16

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?

sastanin
  • 40,473
  • 13
  • 103
  • 130
  • Personally, I think this is deeply objective. Just browse through the standard libs and see, how many of them are "provisional" or "experimential". – fuz Oct 01 '10 at 16:57
  • 2
    That's exactly what bothers me. If even the core libraries are mostly only provisional and experimental, then what we, the mere mortals, can claim about our code? I don't like calling everything equally provisional, but I'd like to see how people understand this. – sastanin Oct 01 '10 at 21:46

3 Answers3

12

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.

dfeuer
  • 48,079
  • 5
  • 63
  • 167
Simon Marlow
  • 12,785
  • 4
  • 42
  • 32
5

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.

Max Bolingbroke
  • 2,089
  • 18
  • 18
  • Yup. Or replace it with a system for opting in to a versioning policy, e.g. standard Package Versioning Policy. http://www.haskell.org/haskellwiki/Package_versioning_policy – Duncan Coutts Oct 13 '10 at 21:23
4

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.

Rudy Matela
  • 6,310
  • 2
  • 32
  • 37