Re: [RFC2] Handling Backwards Compatibility in PEAR

Hi! Greg Beaver wrote:

[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.

Public API: methods that are explicitly marked 'public' and are documented either in peardoc or on package's homepage.

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.

+1 mostly, comments below

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.

-1 Saner versioning: ----------------- Most well-known opensource projects use *two* leftmost numbers of their version string as major version number. Minor releases' versions change only in third and later numbers. Thus: Major release: current version string differs from version string of the previous release in first or second number. Example: Foo 1.1.9 -> Foo 1.2, Foo 1.3 -> Foo 2.0 Minor release: current version string differs from version string of the previous release in third or later number only. Example: Foo 1.0 -> Foo 1.0.1, Foo 1.1.2 -> Foo 1.1.9 Increasing the leftmost version number should be generally reserved for 'milestones' in the package development: * Feature additions that can be of interest for most of the package's userbase * Ground-up rewrite of the package * Change of maintainer Changes to public API (except for feature additions) should happen only in major releases. Announcing API changes: ----------------------- If there is a need to remove a public (as defined above) method, then 1) If it is possible to implement the same functionality in other methods then such functionality should be added and the method should be marked deprecated in major release. This means that the method can be removed in any of the following major releases. 2) If it is not possible to implement the same functionality or if the method is removed due to API simplification then the package should enter beta stage before the next major release. Reasoning: API breaks will not happen without due warning. If you do not use deprecated methods and the next major version comes out, you can safely upgrade to it. If the package you depend upon enters alpha/beta stage, then you should test for compatibility before upgrading.

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.

+1 here

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.

+1 here, with the above definition of 'major'.

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

A public announcement of this should be required with a concrete reason for removal.