hackage.haskell.org documentation convention meaning

Question

I am currently reading http://hackage.haskell.org/packages/archive/containers/latest/doc/html/Data-Set.html#t:Set

What does following detail convey (to an absolute haskell beginner)?

Portability: portable (Which other are portability value?)
Stability: provisional (Which other are stability value?)
Maintainer: [email protected]
Safe Haskell: Safe (Is there something unsafe?)

Answer 1

The fields come from the package's .cabal file, which lists some metadata for the package. Many fields can have free-form values, so that the developer decides for him/herself what to write in that field, and there are no fixed "rules" for what each field must not contain.

Portability: Describes how portable the package is between Haskell compilers, and sometimes also between operating systems. The only values I've seen are "portable" and "unportable". An unportable package is a package that maybe depends on a Haskell language extension that only exists in the GHC compiler, and doesn't work on any other Haskell compiler like UHC, or that maybe depends on some system library that only exists in UNIX and doesn't work in Windows.

Stability: Specifies how stable a library is, which includes its reliability (e.g. how often it crashes), but most importantly how often its API changes. I've seen the values "experimental", "provisional" and "stable", but there might be a list with more somewhere (Things in the Cabal documentation are sometimes impossible to find). When a package is experimental, it means that its interface probably changes between every release, because the developer hasn't decided on how it should be implemented yet, or because the developer just implemented some theoretical functionality from a paper somewhere, and doesn't intend to maintain the package; s/he just wanted to implement the functionality to see if it was possible and is publishing the package as a demonstration. When a package is provisional, it means that the general API is stable, so that there might be updates to the package that only fixes internal bugs and doesn't add or remove any functions. Because it is provisional, however, it might change in the future when the developers decide to add new features or restructure the library. With a stable library, this basically never happens; the API will probably never change, and the implementation is "rock solid" or a reference implementation of an API or something.

The maintainer for a package is the person or group of persons who are responsible for the package. The email specifies how these maintainers can be reached.

The "Safe Haskell" field refers to a GHC extension which you can read more about here. A module which is unsafe uses functions like unsafePerformIO which breaks some of the fundamental "rules" of Haskell like referential transparency. An unsafe module might also use unsafe language extensions. A safe module is a module that doesn't use any unsafe functions etc, and also doesn't import any other unsafe modules. A trusted module uses unsafe functions (Directly trustworthy, indirectly trusted), but the author has made sure that the public API of the module hides this fact safely, so that from the outside it seems like the module is safe for all intents and purposes. Those are the options for the "Safe Haskell" field.