pear:rfc:pear2_versioning_standard_revision

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Next revision
Previous revision
pear:rfc:pear2_versioning_standard_revision [2009/06/27 16:09]
cellog created
pear:rfc:pear2_versioning_standard_revision [2017/09/22 13:28] (current)
Line 7: Line 7:
   * Title: PEAR2 Versioning Standards Revision   * Title: PEAR2 Versioning Standards Revision
   * Version: ​  0.1.0   * Version: ​  0.1.0
-  * Status: ​   ​Incomplete+  * Status: ​   ​Draft
   * Type:      Standards   * Type:      Standards
-  * Last updated: ​June 27, 2009+  * Last updated: ​December 29, 2009
 ==== Author(s) Information ==== ==== Author(s) Information ====
  
   * Name:  Gregory Beaver   * Name:  Gregory Beaver
   * Email: cellog@php.net   * Email: cellog@php.net
 +  * Name:  Brett Bieber
 +  * Email: saltybeagle@php.net
  
 ==== Legal Information ==== ==== Legal Information ====
Line 73: Line 75:
  
 This document describes the versioning standards for the PEAR2 repository that will make the This document describes the versioning standards for the PEAR2 repository that will make the
-paranoia setting work.+paranoia setting work, and defines the version and api numbering process when backwards compatibility is broken. 
 + 
 +Breaking backwards compatibility requires changing the major '​A'​ in the A.P.I version. Once a package has been released as '​stable'​ the 
 +changing the major '​A'​ in the A.P.I version requires changing the major version '​X'​ in the X.Y.Z version in the package version.
  
 ===== Approach & Requirements ===== ===== Approach & Requirements =====
Line 86: Line 91:
 First, some framework basics: First, some framework basics:
  
- - The first API version of a new, non-stable package shall be 0.1.0 +  ​- 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 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+  - The API version of the first stable release shall be 1.0.0, independent of the following rules
  
-Nextthe API version ​number calculator:​ +otherwise, API version ​shall be set by the following ​pseudo-code:​
- +
-Follow ​the pseudo-code ​below to determine API version:+
  
    ​$version = lastAPIversion();​    ​$version = lastAPIversion();​
    ​$version = explode($version);​    ​$version = explode($version);​
 +   ​$stability = APIStability();​
    $X = $version[0];​    $X = $version[0];​
    $Y = $version[1];​    $Y = $version[1];​
    $Z = $version[2];​    $Z = $version[2];​
-   if (Breaking ​backwards compatibility) {+   if ($X >= 1 && First release breaking ​backwards compatibility) {
        $X += 1;        $X += 1;
        $Y = 0;        $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.+       $Z = 0; // so version 1.2.3 becomes 2.0.0 or 2.0.0a1 for alpha, 2.0.0b1 for beta API, etc. 
 +       if ($X >= 1) { 
 +           if ($stability will be alpha) { 
 +               $Z .= '​a1';​ // version 1.2.3 would become 2.0.0a1 
 +           } elseif ($stability will be beta) { 
 +               $Z .= '​b1';​ // version 1.2.3 would become 2.0.0b1 
 +           } 
 +       }
    } elseif (adding new features) {    } elseif (adding new features) {
        $Y += 1;        $Y += 1;
        $Z = 0; // so version 1.2.3 becomes 1.3.0        $Z = 0; // so version 1.2.3 becomes 1.3.0
-   } elseif (fixing bugs only) {+   } elseif (fixing bugs in API only) {
        $Z += 1; // so version 1.2.3 becomes 1.2.4        $Z += 1; // so version 1.2.3 becomes 1.2.4
    }    }
 +
 +An "API bug" is defined as a mismatch between the program'​s behavior and the documented behavior.
  
 The next section addresses release version. The next section addresses release version.
Line 114: Line 127:
 First, some framework basics: First, some framework basics:
  
- - The first Release version of a new, non-stable package shall be 0.1.0 +  ​- 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+  - The first Release version of a release candidate shall be 1.0.0RC1 
 +  - The first Release version of release candidates for major changes shall have "​RC1"​ appended to the stable release (1.2.0RC1, 2.0.0RC1, etc.) 
 +  ​- 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:​+otherwise, ​Release version shall be set by the following pseudo-code:​
  
    ​$version = lastreleaseversion();​    ​$version = lastreleaseversion();​
    ​$version = explode($version);​    ​$version = explode($version);​
 +   ​$stability = releaseStability;​
    $X = $version[0];​    $X = $version[0];​
    $Y = $version[1];​    $Y = $version[1];​
    $Z = $version[2];​    $Z = $version[2];​
-   if (Breaking ​backwards compatibility -or- adding major new features) {+   if ($X >= 1 && (First release (breaking ​backwards compatibility -or- adding major new features))) {
        $X += 1;        $X += 1;
        $Y = 0;        $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.+       $Z = 0; // so version 1.2.3 becomes 2.0.0 
 +       if ($X >= 1) { 
 +           if (will be alpha) { 
 +               $Z .= '​a1';​ // version 1.2.3 would become ​2.0.0a1 
 +           } elseif (will be beta) { 
 +               $Z .= '​b1';​ // version 1.2.3 would become ​2.0.0b1 
 +           } 
 +       }
    } elseif (adding new features) {    } elseif (adding new features) {
        $Y += 1;        $Y += 1;
Line 134: Line 157:
        $Z += 1; // so version 1.2.3 becomes 1.2.4        $Z += 1; // so version 1.2.3 becomes 1.2.4
    }    }
 +
 +===== Other Examples =====
 +
 +For the next release after version 0.1.0/0.1.0 (API/​Release):​
 +
 +   still unstable:
 +   ​Breaking BC: API 0.2.0, Release 0.2.0
 +   ​Adding major features: API 0.2.0, Release 0.2.0
 +   ​Adding minor features: API 0.2.0, Release 0.2.0
 +   ​bugfix:​ API 0.1.0, Release 0.1.1
 +   API bugfix: API 0.1.1, Release 0.1.1
 +
 +   ​moving to beta: API 0.2.0, Release 0.2.0
 +
 +   ​moving to release candidate: API 1.0.0, Release 1.0.0RC1
 +   next release candidate: API 1.0.0, Release 1.0.0RC2
 +
 +   ​moving to stable: API 1.0.0, Release 1.0.0
 +
 +
 +For the next release after version 1.0.0/1.0.0 (API/​Release):​
 +
 +   ​moving to alpha:
 +   ​Breaking BC: API 2.0.0a1, Release 2.0.0a1
 +   ​Adding major features: API 1.1.0a1, Release 2.0.0a1
 +   ​Adding minor features: API 1.1.0a1, Release 1.1.0a1
 +   ​bugfix:​ <not applicable>​
 +   API bugfix: <not applicable>​
 +
 +   ​moving to beta:
 +   ​Breaking BC: API 2.0.0b1, Release 2.0.0b1
 +   ​Adding major features: API 1.1.0b1, Release 2.0.0b1
 +   ​Adding minor features: API 1.1.0b1, Release 1.1.0b1
 +   ​bugfix:​ <not applicable>​
 +   API bugfix: <not applicable>​
 +
 +
 +   ​moving to release candidate:
 +   ​Breaking BC: API 2.0.0, Release 2.0.0RC1
 +   ​Adding major features: API 1.1.0, Release 2.0.0RC1
 +   ​Adding minor features: API 1.1.0, Release 1.1.0RC1
 +   ​bugfix:​ <not applicable>​
 +   API bugfix: <not applicable>​
 +
 +   ​moving to stable:
 +   ​Breaking BC: API 2.0.0, Release 2.0.0 <This is *not* recommended ever>
 +   ​Adding major features: API 1.1.0, Release 2.0.0
 +   ​Adding minor features: API 1.1.0, Release 1.1.0
 +   ​bugfix:​ API 1.0.0, Release 1.0.1
 +   API bugfix: API 1.0.1, Release 1.0.1
 +
 +
 +===== A typical life cycle =====
 +
 +   API 0.1.0/​alpha, ​    ​Release 0.1.0/alpha
 +   API 0.1.0/​alpha, ​    ​Release 0.1.1/​alpha ​   <-- bugfix
 +   API 0.1.1/​alpha, ​    ​Release 0.1.2/​alpha ​   <-- API bugfix, bugfix
 +   API 0.2.0/​alpha, ​    ​Release 0.2.0/​alpha ​   <-- major new features, bugfix
 +   API 0.3.0/​alpha, ​    ​Release 0.3.0/​alpha ​   <-- minor new features, bugfix
 +
 +   API 0.4.0/​beta, ​     Release 0.4.0/​beta ​    <​-- bugfix, minor new features
 +   API 1.0.0/​stable, ​   Release 1.0.0RC1/​beta ​ <-- bugfix, API freeze
 +   API 1.0.0/​stable, ​   Release 1.0.0RC2/​beta ​ <-- bugfix, API frozen
 +   API 1.0.1/​stable, ​   Release 1.0.0RC3/​beta ​ <-- API bugfix, bugfix
 +   API 1.0.1/​stable, ​   Release 1.0.0/​stable ​  <​-- ready for production use
 +
 +   API 1.0.1/​stable, ​   Release 1.0.1/​stable ​  <​-- bugfix
 +   API 1.0.1/​stable, ​   Release 1.0.2/​stable ​  <​-- bugfix
 +   API 1.0.2/​stable, ​   Release 1.0.3/​stable ​  <​-- bugfix, API bugfix
 +
 +   API 1.1.0/​stable, ​   Release 1.1.0/​stable ​  <​-- minor feature addition
 +   API 1.1.0/​stable, ​   Release 1.1.1/​stable ​  <​-- bugfix
 +
 +   API 1.2.0a1/​alpha, ​  ​Release 1.2.0a1/​alpha ​ <-- major feature addition (note that this could be 2.0.0a1 as well, it is up to the developer)
 +   API 1.2.0a2/​alpha, ​  ​Release 1.2.0a2/​alpha ​ <-- bugfix, API bugfix
 +   API 1.2.0b1/​beta, ​   Release 1.2.0a3/​alpha ​ <-- API stabilizing,​ code still unstable, bugfix
 +   API 1.2.0/​stable, ​   Release 1.2.0RC1/​beta ​ <-- API frozen, code stable, bugfix
 +   API 1.2.0/​stable, ​   Release 1.2.0/​stable ​  <​-- ready for production use
 +
 +   API 2.0.0a1/​alpha ​   Release 2.0.0a1/​alpha ​ <-- Backwards compatibility break
 +   API 2.0.0b1/​beta ​    ​Release 2.0.0a2/​alpha ​ <-- API stabilizing,​ code still unstable, bugfix
 +   API 2.0.0/​stable ​    ​Release 2.0.0b1/​beta ​  <​-- API stable, frozen, code still unstable, bugfix
 +   API 2.0.0/​stable ​    ​Release 2.0.0RC1/​beta ​ <-- code stable, API stable, bugfix
 +   API 2.0.0/​stable ​    ​Release 2.0.0/​stable ​  <​-- ready for production use
  
 ===== Expiration ===== ===== Expiration =====
pear/rfc/pear2_versioning_standard_revision.1246118951.txt.gz · Last modified: 2017/09/22 13:28 (external edit)