Differences

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

--- rfc:peclversioning [2008/04/02 11:31] – pajoye
+++ rfc:peclversioning [2008/07/16 13:00] – Fix URLs scottmac
@@ Line 1: / Line 1: @@
 ===== Request for Comments: PECL Versioning =====
-  * **Author:** Steph Fox, Pierre A. Joye
-  * **Status:** Work in progress
 === The Problem ===
-Currently, PECL versioning is fairly anarchic. Looking into the problem of distributing PECL binaries, this is one of the first areas that could and should be addressed.
+Currently, PECL versioning is fairly anarchic. It is impossible to determine the status of an extension, or whether an update will break binary compatibility with previous versions (or work with a given PHP release) without a long try-&-fail process. Windows PECL binaries should have reliable version information in the DLL resources (physically visible in the file properties) as well as at runtime (through phpinfo(), phpversion('extname') etc.). Some of the processes in php.net that currently use hard-coded lists could also benefit from a standardized versioning process. This problem has to be fixed to bring PECL to a higher quality and reliability level.
-=== Requirements ===
+There are actually two RFCs (proposals) to deal with version numbering in PECL and for core PHP extensions in general.
-Each PECL package has to follow the following requirements:
+  * [[rfc:peclversioning/solution1|Base proposal]] by Steph Fox
+  * [[rfc:peclversioning/solution2|Extended proposal]]  by Pierre A. Joye
-  * Declare PHP_EXTNAME_VERSION in php_extname.h
-  * Use PHP_EXTNAME_VERSION in every place where the version information is used, for example in both the zend_module_entry declaration and PHP_MINFO() (the phpinfo() source)
-  * The "-dev" postfix has to be used in CVS, in each branch. At packaging time, remove it, create your package, tag the CVS tree and add it again
-  * Use a recognized versioning structure (so that version_compare() can be useful and users can easily see which version they have). See [[|Version naming]] for a detailed explaination.
-=== Optional version information ===
-  * The cvs $Revision$ or $Id$ (or their equivalent in other source control system) placeholder can be used without restriction but it can't be used as a version number
-=== Version Naming ===
-There is two kind of packages in PECL, a normal PHP extension providing a set of APIs (http, enchant, fileinfo)and extension providing only data (timezonedb). Normal extensions have to use the standard version number defined below as the data package can use a date time version:
-   * Standard version: 2.2.11 Major
-   * Date time version: 2008.2 (for february 2008) or 2008.04.4 (April 4th, 2008)
-== Detailed version number explanation ==
-    * A version number must include a major, a minor and a patch level version number. Please note that all are version numbers are mandatory.
-    * A package version has a "state" (as indicated in the package.xml file), which describes the maturity. The state may be one of "dev", "alpha", "beta", "RC" or "stable" (listed in the order of code maturity). Please note that the state "RC" is achieved by using the state "beta" and appending the version number with "RC" followed by an integer
-      * //PEAR doesn't recognize hyphens (that is, x.x.x(-dev|-alpha|-beta|RC)) in a package version string - use x.x.xax|x.x.xbx instead of than -alpha|-beta.//
-    * A backwards-compatability break may include feature additions
-    * A feature addition may include bug fixes
-    * The version name is always computed on the version name of the release, on which the new release is based, if one exists.
-    * The version number must be greater or equal than 0.1.0
-    * All initial releases of a package with states "dev", "alpha", or "beta" prior to the first stable release should have a version number less than "1.0.0".
-    * The first release with state "RC" or "stable" must have a version number of "1.0.0".
-    * There may not be a stable release unless there has been at least one release before with the same major version.
-    * BC may only be broken in releases that have a version number of "x.0.0" with a state lower than stable or that have a version number below "1.0.0". As a converse only releases that break BC or that have a version number of "1.0.0" may increase the major version number compared to the previous release.
-    * Features may only be added in releases that have a version number of "x.y.0" (where "y > 0"). As a converse the minor version may only be increased in releases that add features.
-    * For releases that only fix bugs the version number should be "x.y.z" (where "z > 0") unless the maturity state is increased. As a converse the patch level number should only be used (as in non zero) in releases that only fix bugs.
-    * The state should always be added as a suffix unless the state is "stable" (please note that as stated above the state "beta" is used for beta releases and for release candidates). The suffix consists of the state followed by a number which is incremented with every subsequent release with the same state.
-    * In the lifecycle of a package each major version increase it is only once (once from major version number 0 to 1, from 1 to 2 etc.).
-== Example: Lifecycle of a package ==
-^ Release type ^ Changes ^ Version ^ Notes ^
-| development release | initial release | 0.1.0dev1 | initial version |
-| development release | features added | 0.2.0dev1 | BC break allowed |
-| alpha release | features added | 0.9.0alpha1 | BC break allowed - but discouraged |
-| beta release | bug fixes | 0.9.0beta1 | BC break allowed - but discouraged |
-| beta release | bug fixes | 0.9.0beta2 | BC break allowed - but discouraged |
-| RC release | bug fixes | 1.0.0RC1 | BC break allowed - but heavily discouraged |
-| stable release | no changes | 1.0.0 | BC break is not allowed |
-| stable release | bug fixes | 1.0.1 | BC break is not allowed |
-| development release | features added | 1.1.0dev1 	BC break is not allowed |
-| beta release | bug fixes | 1.1.0beta1 | BC break is not allowed |
-| stable release | bug fixes | 1.1.0 | BC break is not allowed |
-| stable release | features added  | 1.2.0 | BC break is not allowed |
-| development release | major changes | 2.0.0dev1 | BC break is allowed |
-| alpha release | major changes | 2.0.0alpha1 | BC break is allowed - but discouraged |
-| beta release | bug fixes | 2.0.0beta1 | BC break is allowed - but discouraged |
-| RC release | features added | 2.0.0RC1 | BC break is allowed - but heavily discouraged |
-| RC release | bug fixes | 2.0.0RC2 | BC break is allowed - but heavily discouraged |
-| stable release | bug fixes | 2.0.0 | BC break is not allowed |
-| stable release | bug fixes | 2.0.1 | BC break is not allowed |
-=== Some Facts and Figures ===
-There are currently 214 modules in PECL. Of these:
-  * 1 is written in PHP
-  * 3 are SAPIs
-  * 2 are no longer hosted in PECL (and should be deleted)
-  * 1 doesn't declare a zend_module_entry
-  * 1 doesn't have versioning capability (pre-PHP 4.1?)
-  * 1 was a CVS error (and should be deleted)
-  * 1 is the timezone library for ext/date, and probably has non-standard versioning requirements
-Of the remaining 204:
-  * 13 already use PHP_EXTNAME_VERSION declared in php_extname.h, but don't use -dev
-  * 25 already declare and use a versioning macro in php_extname.h, but the name could be anything
-  * 27 already declare and use a versioning macro somewhere in the source
-  * 3 do the whole thing in reverse and use the release version from package.xml
-  * 136 either hard-code the version, use $Id alone, use $Revision alone or ignore the whole thing
-=== Update 22/3/08 ===
-I committed a change to the Windows build script to enable independent versioning for PECL modules in DLL properties.
-=== Update 24/3/08 ===
-Following discussion, it was agreed that use of $Id/$Revision should be the choice of the extension developer.
-=== Update 25/3/08 ===
-Open items:
-  * The problem of PHP version-specific PECL builds
-  * The problem of core module versioning
-  * Labelling core modules as such on the pecl.php.net project homepage
-  * Labelling PECL releases with their target PHP branches on the pecl.php.net project homepage
-=== Update 2/4/08 ===
-Most of the modules in PECL now comply fully with the following rules:
-  * use x.x.x numbers for versioning
-  * tag the version with '-dev' during the development cycle, thereby distinguishing snaps from release builds
-  * declare the macro PHP_EXTNAME_VERSION in php_extname.h
-  * use the macro in zend_module_entry (so phpversion('extname') will work)
-  * use the macro in PHP_MINFO (so phpinfo() will include module versioning information)
-  * express alpha, beta or RC using the format: 1.0.1a2, 1.0.0RC3, 2.5.3b1
-The seven 'private' extensions are slightly behind the rest. The dev teams involved have been alerted and asked to update their versioning structure.
-Two modules (maxdb and timezonedb) use a versioning structure based on third-party code that can't sensibly be altered.
-One module (APC) already uses the proposed versioning structure, but declares a non-standard macro in a non-standard header. A handful of other modules (less than a dozen) declare their standard macro in a non-standard file. I'll do what I can to bring all modules fully into line, since a reliable convention potentially allows the declaration to have uses beyond populating Windows DLL properties. We could remove the hard-coded lists from our snaps scripts, for one...
-One standard module (wxWidgets) doesn't yet declare a PHP_MINFO() function and can't be built for testing in order to add it. The author has been contacted and asked to add this.
-Obvious CVS errors and any modules containing no code have been deleted from PECL. As a side-effect, so have the final two GPL'd extensions.
-Hartmut Holzgraefe has updated PECL_Gen to reflect the new versioning requirements.
-=== Core modules ===
-Johannes Schlueter - as Release Master of the PHP 5.3 series - made it known early in the proceedings that he has concerns over -dev, -alpha or -beta tags appearing in PHP core module versions. There's no process in place to export PECL releases into the PHP core; many of the modules in PECL are symlinked into the PHP core, affecting both snapshots and releases. This has benefits for the PECL modules concerned, in that they get far more testing than they otherwise might during the PHP development cycle, but the point remains that they are linked directly rather than filtered through an independent PECL release process.
-The idea of using the tag '-core' rather than '-dev' to reflect the status of those dual-nature extensions came up. The PECL versioning could then remain x.x.x (no tag) during PECL releases, with the version number itself used to reflect alpha/beta development status. Christopher Jones of Oracle voiced his concern regarding core PECL modules in separate development branches, which happens with core symlinking (and can of course occur manually too). "Should the version in CVS HEAD be tagged -core6?" Pierre Joye recommended that module versions with a conflicting API simply reflect this in the version number, e.g. 1.0.3-core for PHP 5.* and 2.0.3-core for PHP 6. The PECL releases would be 1.0.3 and 2.0.3 respectively, and the version bumped to 1.0.4-core/2.0.4-core following release.
-**//Feedback on this subject would be appreciated!//**
-=== Please comment on the pecl-dev mailing list ===

Differences

Page Tools