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] – created cellogpear:rfc:pear2_versioning_standard_revision [2017/09/22 13:28] (current) – external edit 127.0.0.1
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.txt · Last modified: 2017/09/22 13:28 by 127.0.0.1