This document has been published on 14th November 2003 and describes how releases that break backwards compatibility (BC) have to be handled.

The goal is to make it possible to be able to run multiple major versions in one script.

For this reason new major versions (BC break or when the maintainer feels it makes sense as a result of dramatic feature additions or rewrites) require a new package using the following naming convention in the following order of preference (where 'Foo' is the package name and 'X' the major version number):

1. FooX
2. FoovX
3. Foo_vX

The choice should be made based on preventing current and future misleading or ambiguous names. This means good care should be taken in making the right choice for the package. Obviously the first two allow for some ambiguity (is DB2 a package for IBM's DB2 or just the major version 2 of DB? - is IPv4 a package for IPv4 or is it the 4th major release if IP?). They don't break the idea of "_" mapping to directories (the class DB_NestedSet implies that there is a nestedset.php in the DB dir). The last one prevents any ambiguity but it's the least visually pleasing and also breaks the '_' to directory mapping and is therefore the last choice.

We also came to the conclusion that the pear installer should not be clever about the relationship between two major releases aside from printing out notices about the fact that there is a newer major version when a user installs an earlier one. However all major versions of a package will be listed on one package home. This is especially important in order to not break tutorials that cover older major releases (tutorial xyz for major version 1 simply says 'pear install Foo' - if the system would then install 'Foo2' the user might be in for an unpleasant surprise).

Therefore, new major versions are for all intents and purposes new packages with the above mentioned exceptions. The names of these new packages are derived using one of the above mentioned naming conventions.