Summary

• Title: PEAR2 Versioning Standards Revision
• Version: 0.1.0
• Status: Incomplete
• Type: Standards
• Last updated: June 27, 2009

• Name: Gregory Beaver
• Email: cellog@php.net

• This proposal is under CC-By-Sharealike licensing.

• Mailing List: http://news.php.net/php.pear.dev

Currently, PEAR (and by extension, PEAR2) coding standards forbid breaking backwards compatibility in packages once they reach a stable state. This is due to the difficulty of protecting users from these breaks with the PEAR installer.

This limits innovation by developers and makes their lives harder for the benefit of users. Fortunately, there is a technical solution that can be incoporated into Pyrus that will solve the deficiency of the PEAR Installer.

The setting is called “paranoid.” This would work just like the “verbose” setting in PEAR (and Pyrus), so by passing multiple paranoid options, the paranoia would increase:

  php pyrus.phar -ppp upgrade Blah

would instruct Pyrus to set the paranoia level to 3. Here are the paranoia levels (and what they mean):

1. don't care (I know what I'm doing, upgrade the dang thing)
2. no BC breaks (I'm busy, just don't let it break my stuff)
3. security fixes only (I rely on the API heavily, but I want to keep it secure even if it risks breaking things)
4. no API changes under any circumstance (I have nightmares terrorists will use my server farm to launch nuclear attacks. I sleep with an uzi under my pillow)

in technical terms:

1. any X.Y.Z API version is fine
2. X must not change, Y and Z can change (if installed API version is 1.2.3, any 1.Y.Z can be installed)
3. X and Y cannot change, Z can change (if installed API version is 1.2.3, any 1.2.Z can be installed)
4. X, Y and Z cannot change.

By default, pyrus will set paranoia to “2”, so that BC breaking releases are never upgraded to. The user can override this simply through:

  php pyrus.phar -p upgrade Blah

or

  php pyrus.phar set paranoia 1

to change the default paranoia to “1”

Thus in our example above, User X would not be able upgrade to the new release without explicitly requesting it (although Pyrus would notify him that if he were less paranoid, he could upgrade).

This document describes the versioning standards for the PEAR2 repository that will make the paranoia setting work.

Packages that wish to be accepted into the PEAR2 repository must conform to these standards

All packages must actively manage the API version and stability in addition to the Release version and stability.

First, some framework basics:

- The first API version of a new, non-stable package shall be 0.1.0 - The API version of any beta/release candidate prior to a stable release shall be the same as the stable release, so for example, version 1.0.0RC1 shall have API version 1.0.0 - The API version of the first stable release shall be 1.0.0, independent of the following rules

Next, the API version number calculator:

Follow the pseudo-code below to determine API version:

 $version = lastAPIversion();
 $version = explode($version);
 $X = $version[0];
 $Y = $version[1];
 $Z = $version[2];
 if (Breaking backwards compatibility) {
     $X += 1;
     $Y = 0;
     $Z = 0; // so version 1.2.3 becomes 2.0.0 or 2.0.0a1 for alpha, 2.0.0b1 for beta, etc.
 } elseif (adding new features) {
     $Y += 1;
     $Z = 0; // so version 1.2.3 becomes 1.3.0
 } elseif (fixing bugs only) {
     $Z += 1; // so version 1.2.3 becomes 1.2.4
 }

The next section addresses release version.

First, some framework basics:

- The first Release version of a new, non-stable package shall be 0.1.0 - The Release version of the first stable release shall be 1.0.0, independent of the following rules

Release version shall be set by the following pseudo-code:

 $version = lastreleaseversion();
 $version = explode($version);
 $X = $version[0];
 $Y = $version[1];
 $Z = $version[2];
 if (Breaking backwards compatibility -or- adding major new features) {
     $X += 1;
     $Y = 0;
     $Z = 0; // so version 1.2.3 becomes 2.0.0 or 2.0.0a1 for alpha, 2.0.0b1 for beta, etc.
 } elseif (adding new features) {
     $Y += 1;
     $Z = 0; // so version 1.2.3 becomes 1.3.0
 } elseif (fixing bugs only) {
     $Z += 1; // so version 1.2.3 becomes 1.2.4
 }

This standard will become a part of the PEAR2 standards, and expire at the same time the PEAR2 standards expire.

None