Section 12.3. Release Versioning

12.3. Release Versioning

This section assumes that you have read the "Version Numbers" section in Chapter 10.

The first rule defines the version number of the first stable release:

• The first stable release of a package must use the version number 1.0.0.

• Releases prior to the first stable release must use a 0.x version number, and must not be stable.

• Backward compatibility may be broken arbitrarily between 0.x releases.

  After the first stable release, some more rules start kicking in:

• Release 1.N must be compatible with 1.M where N > M. For example, 1.3 must be compatible with 1.2.

• Release N.x may break compatibility with M.x where N > M. For example, 3.0 may break compatibility with 2.4.

• New features require that the minor version increases (for example, 1.2 to 1.3 or 1.2.5 to 1.3.0).

• The patch level is used only for bug-fix releases (for example, 1.2 to 1.2.1, or 1.2.0 to 1.2.1).

In this context, backward compatibility means that code written using one version of a package keeps working correctly with a newer version. When the major version number increases and the new major version is incompatible with the previous major version, the package name has to change by appending the new major version. For example, if you have Foo version 1.9.0 and Foo 2.0.0, and Foo 2.0.0 is not backward compatible, the package is renamed to Foo2. The release still uses the same version number (for example, Foo2-2.0). If for some reason, this scheme does not fit with the package name (for example, if the last character in the package name is already a digit), two alternative forms are accepted: Foov2 and Foo_v2.

The reference implementation for comparing version numbers is PHP's version_compare() function.