pear:rfc:pear2_versioning_standard_revision

Differences

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

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision
Previous revision
Last revisionBoth sides next revision
pear:rfc:pear2_versioning_standard_revision [2009/06/27 16:09] cellogpear:rfc:pear2_versioning_standard_revision [2009/12/29 20:15] – Add api version changes paragraph to the summary saltybeagle
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 90: Line 95:
   - 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 115: Line 128:
  
   - 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 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   - 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.txt · Last modified: 2017/09/22 13:28 by 127.0.0.1