RE: [PEAR-DEV] [RFC2] Handling Backwards Compatibility in PEAR

> From: Greg Beaver [mailto:greg@chiaraquartet.net] > Sent: Friday, September 19, 2003 11:08 PM > [RFC2] Handling Backwards Compatibility in PEAR > Sept. 19, 2003 > Greg Beaver > 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. Uhm I assume this is what you mean: I plan to change the API in a package. I bump the major version number and make a first alpha release. Then I can still change the API without a fuss. I am in a new major version number and being in alpha I have not communicated that the API is fixed. Once I move to beta I should be sure that the API works. But people still should expect that design flaws noticed in the beta process might result in API changes. > 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 I dont understand this. BC break is a major version bump. That's all. > 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. OK > 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. I don't understand this either. There is no problem branching off development. I plan to support MDB 1.x after MDB 2.x has been released. I don't see a reason for this regulation. However I do see a benefit in putting the major version number if a postfix to all classes (and functions I guess too!) in order to make it possible to run two versions of a package in one script. > 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: +1 > The PEAR Installer will also add the revert command, which will restore > a previous installation +1 > 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 I really hope this will not happen. Pierre's work with the BC break detection etc. Regards, Lukas