[RFC2] Handling Backwards Compatibility in PEAR

[RFC2] Handling Backwards Compatibility in PEAR Sept. 19, 2003 Greg Beaver The Problem: ------------ PEAR does not have a system in place to handle backwards compatibility issues. definitions: BC: "Backwards Compatibility" means programs that rely upon a package will still work when the package is upgraded. It is assumed that the programs using the package only use elements of the API, and do not use any private elements. API: "Application Program Interface" is the connection between a package and the programs that use it. This includes class and method names, parameters that are passed to methods, and constant names, or any other publicly accessible area of a program. Private data/methods are excluded from this definition. The Solution: ------------ The API of a PEAR package may break BC if: 1) A package is marked as alpha stability or lower. API may change without warning. 2) Beta-quality packages should have a relatively stable API that may break BC to fix bugs or implement serious gaps in the design that were overlooked - this should happen very rarely with proper design. 3) Stable-quality packages should not break BC, but may add new features to an API if they do not break BC with old features. It is up to the lead developers to determine whether BC needs to be broken. It is highly encouraged to carefully select the API before version 1.0 so that changes to the API that break BC will not be necessary. Versioning: ----------- The first stable release of a package is version 1.0. If a package breaks BC at all, the version shall bump to the next whole number, 2.0. If a package intends to remove or change the name of API elements, this must be clearly marked in at least 1 release before they are removed (see HTML_QuickForm). When the API is changed, the version number shall increase to the next whole number. In other words, if the API changes for Foo version 2.7.2, the next release is version 3.0 A complete rewrite of a package that maintains BC with the old API may also bump version number if the package developer wishes to do so. Complete API change: -------------------- If a package is stable, and is rewritten with a completely different API that may need to temporarily co-exist with the older version, then the following solution should be used: Imagine package Foo version 1.6 is the latest stable release of Foo. The next release with a complete API rewrite shall be package Foo2 version 2.0. At this point, package Foo will automatically be considered a deprecated package. Foo2 will be intended to eventually replace Foo in all installations, and all development of new features on Foo will freeze permanently. New development will continue in package Foo2. This solution should only be used if programs that use Foo would require a complete rewrite to use Foo2 - if programs that use Foo could use Foo version 2.0, then Foo should be released as version 2.0, not as a separate package. In addition, the name of all paths and classes shall change to reflect this. file Foo.php: <?php class Foo { } ?> becomes file Foo2.php: class Foo2 { } Changes to the PEAR Installer: ------------------------------ The PEAR Installer will not install a version of a package with a major version number greater than the current major version without the --force option. If a newer minor version of the current major version exists, that will be installed. Example: Package Foo's latest versions are 1.7 and 2.0 $ pear install Foo-1.6 Foo version 1.6 installed successfully $ pear upgrade Foo Foo version 1.7 installed successfully $ pear upgrade Foo-2.0 Cannot upgrade to version 2.0: backwards compatibility is broken, use --force if you are sure this is OK. $ pear upgrade --force Foo-2.0 Foo version 2.0 installed successfully The PEAR Installer will also add the revert command, which will restore a previous installation $ pear upgrade --force Foo-2.0 Foo version 2.0 installed successfully $ php -q usesFoo.php Error: something didn't work right $ pear revert Foo Reverting to version 1.7 of Foo $ php -q usesFoo.php Mmmmmmm, Foo :) $ The same changes apply to the automatic upgrading of dependencies through the --alldeps and --onlreqdeps command-line switches. Infractions: ------------ If a package is released that breaks BC and isn't a major version number increase, the PEAR Group may at their discretion remove the release and require it to be a new major version number --Greg