unified versioning RFC (attempt 2)

Here is another attempt (simpler is not what I mean, unified is closer): Versioning in PEAR is linked heavily to the stability of a package. PEAR defines two kinds of versioning: 1) release version 2) API (application program interface) version A release version is the public version, as in "PEAR version 1.3.5" version 1.3.5 is the release version. An API version is like a description of the external interface to a package, and is defined as the first digit of a release version. PEAR release version 1.3.5 has an API version of "1". API versioning ============== The API version follows this life cycle for a package: Package Foo begins its first cycle with unstable API => API version 0 When Package Foo reaches API and code stability, => API version 1 PEAR does not allow changing an existing API for any reason. New features may be added, but if a change must be made, the package must branch into two separate packages, Foo, and FooX where X is the API version number. In this case, Package Foo would exist with API version 1, and package Foo2 would exist with API version 2. Note that in special circumstances, such as a BC-break in a package like IPv4, exceptions may be made on a case-by-case basis, as IPv42 is *not* a good name, and neither is IPv4_v2. Release versioning ================== The release version must be in the format x.y.z where x is the API version, y is the feature revision level, and z is the bugfix revision level. For every major feature addition, y must be incremented. For minor feature additions, or bugfixes, z must be incremented. If y is incremented, z is reset to 0. If x is incremented, both y and z are reset to 0 (so after 0.34.5, if the API version, x, increases from 0 to 1, 1.0.0 must be the next release version number, after 0.34.5, if the feature revision level, y, increases from 34 to 35, the next version must be 0.35.0). Here is a typical release version life cycle for package Foo: 0.1.0 [first release] 0.2.0 [major feature addition] 0.2.1 [minor feature addition or bugfix] 0.3.0 [major feature addition] 1.0.0RC [API has stabilized, prepare for first stable code release] 1.0.1RC [minor bugfix, prepare for first stable code release] 1.0.2 [first stable release] 1.0.3 [minor feature addition or bugfix] 1.1.0 [major feature addition or bugfix] 1.1.1 [minor feature addition or bugfix] and so on. In addition to numbering requirements for versions, there are also stability requirements, as mentioned in the first sentence. If the API version is 0, the stability must be devel, alpha, or beta. A package whose last release was "alpha" stability may change API in the next release, breaking backwards compatibility at any moment with no penalty. Example: 0.1.0, alpha 0.2.0, alpha (major changes made) 0.3.0, alpha (complete rewrite, no penalty) A package whose last release was "beta" stability may NOT change API, except in the case of egregious bugs that would render the package useless. Incorrect Example: 0.8.0, beta 0.9.0, beta (major bugfixes, no changes to API) 0.10.0, beta (complete rewrite - this is an error, PEAR QA will remove this release) The first stable release must be preceded by at least 1 release candidate, identified by the post-fix "RC" (as in 1.0.0RC). Release Candidates are by definition "beta" stability. Incorrect Example: 0.8.1, beta 1.0.0, stable (this is an error, no release candidates, PEAR QA will remove this release) Correct Example: 0.8.1, beta 1.0.0RC, beta (first release candidate) 1.0.1RC, beta (second release candidate) 1.0.2, stable All releases following the first stable release must be stable, until a major feature addition is made, or major bugfix is made requiring additional testing. Incorrect Example: 1.0.2, stable 1.0.3, stable 1.0.4, beta (this is not allowed, the version should be 1.1.0) Correct Example: 1.0.2, stable 1.0.3, stable 1.1.0, beta (introduce major new features) 1.0.4, stable (this is allowed, incidentally, to do a point release for the 1.0.* feature set while developing the 1.1.* feature set) 1.1.1, beta (minor bugfixes) 1.1.2, stable (first stable release of major new features) When the API version increments, and a new package is spawned (Foo2 from Foo), the versioning will continue as it has for API version 1. Example: Package Foo2 versioning life cycle: 2.0.0, alpha (first release) 2.1.0, alpha (major new features added) 2.2.0, alpha (major new features added) 2.2.1, alpha (minor bugfix) 2.3.0, beta (prepare for stable release, freeze the API) 2.3.1, beta (minor bugfix) 2.3.1RC, beta (first release candidate) 2.3.2RC, beta (second release candidate) 2.3.3, stable (first stable release) Special Exceptions ================== For packages such as IPv4, where a complete rename must occur, the package should be considered a completely separate, unrelated package that implements the same protocol, and as such, should have a name that does not connect it with existing packages very strongly. In this case, versioning should reset, and start over from 0.1.0.