[RFC] Versioning rules for PHP/Zend/PEAR/Extensions

Maybe this time people notice this? --Jani ============================================================================== 1. Why are these rules needed ? ------------------------------- People expect that software releases follow certain rules for versioning. PHP/Zend/PEAR/extensions don't have any. This makes it very hard, sometimes even impossible, to write: a) Portable scripts b) Portable 'standalone' PEAR/C-extensions (portable == works between different versions of PHP/Zend and/or some extension.) function_exists() could of course be used in some cases, but it is not even needed if these rules are followed. 2. General rules for PHP, Zend and PEAR/C-extensions ---------------------------------------------------- v.m.b (e.g. 4.0.8) v = Functions removed, function behaviour changed, API changes, major parts rewritten. (BC might be broken) m = New functionality added. Only backwards compatible API changes. (100% BC) b = Bug fixes. No new functions added. No API changes. (100% BC) Left out if zero (0). (BC = backwards compatibility) Betas: v.m-betax (e.g. 4.1-beta1) RCs: v.m-RCx (e.g. 4.2-RC2) 3. Stable/development branches [OPTIONAL] ------------------------------ Even minor number: stable (x.2.x) branch. Odd minor number : development (x.3.x) branch. (this is not needed for PHP. Our stable branch can be the release branch and the development branch is just the HEAD) 4. Extension/PEAR versioning ---------------------------- PHP, Zend and (PEAR/C) extensions all must follow the same rules to avoid confusion and also to be able to use the same version checking tools everywhere. EXPERIMENTAL extension versioning: v = 0. ie. 0.x.x When the extension is considered stable, v is bumped up to 1. 5. New PHP/Zend API function version_compare() ---------------------------------------------- proto int version_compare(string version1, string version2 [, string operator]) This function knows this: 4.0.5 < 4.0.6RC2 < 4.1.4 < 4.2-RC1 and returns: -1 version1 < version2 0 version1 === version2 1 version1 > version2 If optional 3rd parameter is used, the function returns 1 when test is true and 0 when test is not true. Optional operator can be: lt = less than le = less than or equal eq = equal gt = greater than ge = greater than or equal ne = not equal example: if(version_compare(phpversion(), "4.2", "lt") || version_compare(phpversion(), "4.0.6", "ge") ) { die("PHP version between 4.0.6 < 4.2 is required."; } Scripts that are intended to be portable between different versions of PHP/Zend just need to check that the version number of the used extension/PHP is greater/equal to certain version and under next major version of the required version. Extensions can use the same function internally to check the Zend / PHP versions. 6. Modification to phpversion() function ---------------------------------------- New optional argument: proto string phpversion([string extension]) This function can then be used also to retrieve the extensions versions and thus be used together with the new version_compare() function. 7. Backwards compatibility -------------------------- As long as the rules are followed and the major number is bumped up when BC is broken this is not a problem.