===== Request for Comments: PECL Versioning =====
  * **Author:** Steph Fox
  * **Status:** Work in progress

=== History ===
PECL versioning has historically been fairly anarchic. From a user perspective, this made it impossible to determine the status of an extension, or whether an update would break binary compatibility with previous versions - or work with a given PHP release - without falling back on trial-and-error. From a developer perspective, it was impossible to know exactly which code base a given bug was reported against. Windows PECL binaries should have reliable version information in the DLL resources (physically visible in the file properties), and PECL packages across all platforms should have this information available at runtime through phpinfo(), phpversion('extname') etc. Some of the processes in php.net that currently use hard-coded extension lists could also benefit from standardized versioning within the source files.

=== Update ===
As of April 2008, all PECL packages should use the PHP_EXTNAME_VERSION macro appropriately and declare the macro in the file //php_extname.h//, and all but a handful have been altered to do so. The one area that is still open for discussion concerns PECL packages that are also core extensions in one or more versions of PHP.

=== Requirements ===

Each PECL package should adhere to the following requirements:

  * Declare PHP_EXTNAME_VERSION in php_extname.h
  * Use PHP_EXTNAME_VERSION in the zend_module_entry declaration (for phpversion())
  * Use PHP_EXTNAME_VERSION in PHP_MINFO() (the phpinfo() source)
  * The "-dev" postfix should be used in CVS during the development cycle. At packaging time, remove it, create your package, tag the CVS tree and then add -dev again and bump the version
  * Use a recognized versioning structure (so that version_compare() can be useful and users can easily see which version they have). See [[|Version naming]].

=== Optional Extras ===

The cvs $Revision$ or $Id$ placeholder may be used in PHP_MINFO(), but cannot replace the version number.

=== Version Naming ===

There are two kind of packages in PECL: normal PHP extensions providing a set of APIs (e.g. http, enchant, fileinfo) and those providing only data (e.g. timezonedb). Normal extensions should use the standard version number defined below. Data packages should use the versioning offered by the underlying package:

   * Standard version: 2.2.11
   * timezonedb version: 2008.2 (for February 2008)

The vast majority of PECL packages fall into the 'normal' category. The basic guidelines for these are:

    * A version string **must** include a major, a minor and a patch level number (x.x.x)
    * The status of the package may be described using 'a', 'b' or 'RC' followed by a numeric value, e.g. '1.2.1b3', '1.0.0rc2', '1.1.0a1'
    * In package.xml, the 'status' field for a release may be any of "dev", "alpha", "beta" or "stable". These states should be reflected in the version number: a "stable" release should be at least 1.0.0, for example. A Release Candidate is signified by RCx in the version number and a "beta" status in package.xml.

If you feel that there should be further guidance, please support Pierre Joye's [[/solution2|extended proposal]] which extends the remit of this one with in-depth guidelines for version numbering in new PECL extensions.

=== Core Modules in PECL ===

Johannes Schlueter - currently Release Master of the PHP 5.3 series - made it known early in the proceedings that he had concerns over -dev, alpha or beta tags appearing in PHP core module versions during a PHP release. 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 ===