This is an old revision of the document!
Request for Comments: PECL Versioning
- Author: Steph Fox, 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.
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
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.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'
- 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 “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 need further guidance, please refer to the extensive PEAR version naming rules at http://pear.php.net/group/docs/20040226-vn.php. The one major difference is that PEAR packages don't need to use '-dev' during the development cycle; there are no snapshot releases of PEAR. 'dev' is therefore used as a release tag in PEAR, but not in PECL, where it would be likely to lead to user confusion.
Core Modules in PECL
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!