• Author: Pierre A. Joye
• Status: Work in progress

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.

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

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.

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

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.y.z) 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 “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
• The state should always be added as a suffix unless the state is “stable” 'a', 'b' or 'RC' (respectively for alpha, beta and release candidate) followed by a numeric value. E.g. '1.2.1b3', '1.0.0RC2', '1.1.0a1'
  • Note that the PEAR installer cannot recognize hyphens in a package version string
• In package.xml, the 'status' field for a release may be any of “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.
• 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 “alpha”, or “beta” prior to the first stable release should have a version number less than “1.0.0”. That obviously does not apply to existing packages moving to PECL (from sourceforge or a private repository) and already had stable releases. However the very first release in pear should be beta to prevent issues with the possible errors due to the move
• The first release with state “RC” or “stable” must have a version number of “1.0.0” (does not apply to existing packages with stable releases and version lower than “1.0.0”)
• 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.).