Re: [RFC2] Handling Backwards Compatibility in PEAR

Lukas Smith wrote:

From: Greg Beaver [mailto:greg@chiaraquartet.net] 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.

Yes, I've modified the text to include a sample release cycle to show exactly what it means: Here is an example release cycle for a package Package Foo: Version 0.1 alpha – initial API Version 0.2 alpha – API changes dramatically, no need to mark it as such Version 0.3 alpha – API changes again, many bugfixes Version 1.0b1 beta – features are in place, API is stabilized Version 1.0b2 beta – major bug results in small API change, bug fixes Version 1.0RC1 beta – API is stable, will not change Version 1.0RC2 beta – API is stable, all known bugs are fixed Version 1.0.0 stable – API is version 1.0 – this release is stable Version 1.1.0 stable – API is version 1.0, a few minor features added Version 1.1.1 stable – API is version 1.0, bugfix release Version 2.0a1 alpha – API is version 2.0, little to no BC with API version 1.0 Version 2.0b1 beta – API is version 2.0 Version 2.0.0 stable – API is version 2.0

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.

Here's a rephrase: 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 last release of package Foo was version 2.7.2, and the next release breaks BC with the API, it must be version 3.0 (or 3.0a1/3.0b1 with a suffix to indicate alpha/beta quality) and should again start the cycle of alpha => beta => stable Is that clearer?

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.

Here's a scenario that may illustrate the need for specifying 1 package is the main package: Package MDB version 1.7 is out, package MDB2 version 2.0 is released. You want to maintain both packages. Say you decide to rewrite a large portion of the core of MDB. This would then suggest you bump the major version to 2.0. Now we have MDB version 2.0, and MDB2 version 2.0. . This is unacceptable ambiguity. Once MDB2 is released, all major development on MDB 1.x is frozen - only bugfixes and minor feature enhancements will be allowed. So, MDB 1.5 or MDB 1.99 or MDB 1.999 is allowed, but never MDB 2.0 if the MDB2 package exists - it is expected that people will switch their code to MDB2 if the MDB package doesn't do what is needed in its current form. Does this make more sense? If so, I'll post a revision 3 after others get a chance to throw in their 2 cents, and once it looks good, perhaps the PEAR Group could take a look at it and seala the deala. I'll write the installer code/revert code, and mod the docs. It will take a little while to get the pearweb code up and working that will handle recognizing MDB2 as MDB version 2.0, unless Martin has some quick fix or something. Greg