Package version
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, setY=Z= 0 -
Adding new features? Yes = increment
Y, setZ= 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.