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:
| 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:
| 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. |