New guidelines for BC breaking releases

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):

FooX

FoovX

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.