Package stability

Versioning and stability are separate entities for packages. The stability of a package determines how likely the package is to contain bugs or to have changes to its API. A distinction is made between the version/stability of the API and the version/stability of the code.

This simple chart shows the meaning of a package's stability:

What a package's stability means
Stability type Stability Description
Release devel The package is under development and will change dramatically, both adding new features, changing the design, and fixing many bugs. It may not function at all and be more of a proof-of-concept. There may be little to no documentation or unit tests. Use at your own risk.
Release alpha The package is ready for testing by hard core users. Features are still being developed, but the program should work. Subsequent releases may have major changes.
Release beta The package is nearly ready for public release and usage in production. Documentation is complete, unit tests are complete, and the API is frozen (will not change) unless major problems are found.
Release stable The package is ready for use in production. Documentation is complete, unit tests are complete, and the API is frozen completely and will not change.
API devel The API will change dramatically between releases, and cannot be relied upon.
API alpha The API is starting to stabilize, but may still have major changes.
API beta The API will only have changes if major bugs are found.
API stable The API will not change and can be relied upon.

There are a few conventions that should be followed when deciding which stability to use for your package. In general, the API stability should be equal to or better than the release stability.

Here is a helpful chart of stabilities:

Which stability to use
Release Stability API Stability Scenario
devel devel This package is brand new, no documentation, no tests, more of a proof-of-concept. It may not work at all.
alpha alpha This package has been developed extensively, and is ready for testing by the outside world, has some documentation or full documentation and tests, but the API or design is subject to dramatic change if necessary. Bugs are likely
alpha beta This package has a relatively certain API, but may contain bugs, and the API may change, but most changes will be small.
beta beta This package is approaching release, the code is stabilizing as well as the API
beta stable This package is in the release candidate stage, has full documentation and tests, as well as a frozen API. Bugs may still be present in the code.
stable stable This package is ready for use in production, has full documentation and tests, and the API can be relied upon as frozen.