Package version
Вернуться к: Basic concepts all PEAR users should understand
Versioning and stability are separate entities for packages. The version of a package is a numeric string like 1.2.3 that is incremented every time a new version of the package is released. The stability of a package determines how likely the package is to contain bugs or to have changes to its API.
In addition, PEAR makes a distinction between the API version and the package version.
Versioning guidelines
There are a few conventions that should be followed when deciding which version number or stability to use for your package. Version numbers should always contain three decimals such as 1.2.3. This is because of the way that PHP's version_compare() function calculates the difference between versions:
<?php
var_dump(version_compare("1.0", "1.0.0")); // int(-1)
?>
The example above shows that in fact version 1.0 is considered to be a different version from version 1.0.0, a distinction that is confusing at best for users. Use of 3 decimals for every version will ensure that both your users and PHP will not be confused by which of two versions is the same or newer.
Package versions can be abstractly referred to as X.Y.Z. For version 1.2.3, X is 1, Y is 2 and Z is 3.
Generally speaking, it is best if X is used to refer to major API changes, sweeping addition of new features, or any break of backwards compatibility. The Y component should be reserved for small to large feature additions, but should never be used for breaks of backwards compatibility. The Z component should only be used for bugfixes.
These three questions can be used to determine how to increase the version number:
-
Breaking backwards compatibility? Yes = increment X, set Y = Z = 0
-
Adding new features? Yes = increment Y, set Z = 0
-
Fixing bugs? Yes = increment Z
Here is a typical life cycle for a package:
| Release Notes | Release Stability | API Stability | Release Version | API Version |
|---|---|---|---|---|
| Initial release | devel or alpha | devel or alpha | 0.1.0 | 0.1.0 |
| Bugs fixed | devel or alpha | devel or alpha | 0.1.1 | 0.1.0 |
| More bugs fixed | devel or alpha | devel or alpha | 0.1.2 | 0.1.0 |
| API changed, more bugs fixed | devel or alpha | devel or alpha | 0.2.0 | 0.2.0 |
| API changed, more bugs fixed | devel or alpha | devel or alpha | 0.3.0 | 0.3.0 |
| API changed, documentation started, tests expanding | alpha | alpha | 0.4.0 | 0.4.0 |
| API stabilizing, documentation nearly finished, tests expanding | alpha | beta | 0.5.0 | 0.4.1 |
| API stabilizing, code stabilizing, documentation nearly finished, tests expanding | beta | beta | 0.5.1 | 0.4.1 |
| API problem fixed, code stabilizing, documentation nearly finished, tests expanding | beta | beta | 0.6.0 | 0.5.0 |
| API stabilized, code stabilizing, documentation nearly finished, tests expanding | beta | stable | 0.6.1 | 1.0.0 |
| API stabilized, code stabilizing, documentation finished, tests expanding | beta | stable | 1.0.0RC1 | 1.0.0 |
| API stabilized, code stabilizing, documentation finished, tests full coverage | beta | stable | 1.0.0RC2 | 1.0.0 |
| code ready for use in production | stable | stable | 1.0.0 | 1.0.0 |
| bugs fixed | stable | stable | 1.0.1 | 1.0.0 |
| bugs fixed | stable | stable | 1.0.2 | 1.0.0 |
| new features added, bugs fixed | stable | stable | 1.1.0 | 1.1.0 |
| bugs fixed, package enters maintenance mode to develop next generation | stable | stable | 1.1.1 | 1.1.0 |
Note that the PEAR coding standards require packages to be renamed when they break backwards compatibility. Thus, a PEAR package can never reach version 2.0.0.
Вернуться к: Basic concepts all PEAR users should understand