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:

  1. Breaking backwards compatibility? Yes = increment X, set Y = Z = 0
  2. Adding new features? Yes = increment Y, set Z = 0
  3. Fixing bugs? Yes = increment Z

Here is a typical life cycle for a package:

A version 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.