Re: [RFC] BC breakage in PEAR - how to handle it properly

Hi! Greg Beaver wrote:

BC breakage in PEAR has not been addressed. If one package depends on version 2.x of a package, and another depends on version 1.x, one package loses in the end. version 1.x can't be installed with version 2.x.

Lets define what is this ever-present "BC breakage": 1) Fixing a long-standing bug in a package for which some workarounds exist is BC breakage. 2) Removing an obscure public method that should never have been public in the first place is BC breakage. 3) Removing methods that were clearly marked as deprecated for several releases is BC breakage. 4) Releasing a new version of package which solves the same problems but has a radically different API is BC breakage. One can come up with more examples, but you probably get the point. What really needs addressing is 4), and there is a solution for this already that just have to be brought to PEAR

Solution: If a minor BC break occurs, or BC is maintained, but a package is completely re-written, a major version number should be incremented in package.xml, and current PEAR systems already in place should be used. The installer should be modified so that a <dep rel="ge" version="1.5"> will fail if the major version is > 1, unless another explicit <dep rel="lt" version="3.0"> is specified.

Against such automatic resolution. If a package Bar depends on Foo then: 1) Foo's maintainer *should* test the new version of Foo package for compatibility with Bar and work out the incompatibilities in cooperation with Bar's developer. If Bar does not have tests for this, that's the problem of Bar's maintainer and Bar's users, but Foo's maintainer *should* atleast notify Bar's maintainer about the upcoming release of Foo. 2) Bar's maintainer should follow the development of Foo. If he does not want to do this, he *should* mark his package as depending on specific version/version range of Foo and deal with users himself, not blame Foo's developer for anything.

If a major BC break occurs, then the package should be released as a new package as detailed below. The solution requires effort on the part of developers only. No changes need be made to the installer, and no changes need be made to package.xml. First, when a new version of a package comes out that is not backwards compatible with an older version, it should be released as a new, separate package. This package shall follow a specific naming scheme Package Foo version 1.x will be named "Foo" Package Foo version 2.x will be named "Foo2" Package Foo version 3.x will be named "Foo3" In addition to these naming conventions, the versioning for Foo2 shall start with major version 1.0 Second, directory structure shall be as follows: Package Foo version 1.x Foo.php Foo/Supporting/FileOne.php Foo/Supporting/FileTwo.php Package Foo version 2.x Foo2.php Foo2/Supporting/FileOne.php Foo2/Supporting/FileTwo.php Third, class naming conventions shall follow the directory structure as well, class Foo2, class Foo2_Supporting_FileOne. In this way, naming and file conflicts cannot happen, and Foo can co-exist with Foo2 Foo.php Foo2.php Foo/Supporting/FileOne.php Foo/Supporting/FileTwo.php Foo2/Supporting/FileOne.php Foo2/Supporting/FileTwo.php Last, supporting files should be unique to a new major version (Foo2 may not depend on Foo/Supporting/FileOne.php, for example) As part of this change, the pear.php.net package listing feature would be smart enough to recognize that Foo and Foo2 are the same package, and link from the package page for Foo to Foo2 and vice-versa.

And that is a solution for case 4) with which I completely agree. I only want to add that a procedure for registering such a new package (that will probably require a separate directory in CVS) should be developed.