92adf051614160febf3e95c5b51ffd0a0908f052wroweAPACHE 2.x VERSIONING
92adf051614160febf3e95c5b51ffd0a0908f052wrowe=====================
a7ff1335befc75bdbfc0addba7306dec7bb6202ccolm[$LastChangedDate$]
92adf051614160febf3e95c5b51ffd0a0908f052wroweINTRODUCTION
92adf051614160febf3e95c5b51ffd0a0908f052wrowe------------
92adf051614160febf3e95c5b51ffd0a0908f052wroweThe Apache HTTP Server project must balance two competing and disjoint
92adf051614160febf3e95c5b51ffd0a0908f052wroweobjectives: maintain stable code for third party authors, distributors and
92adf051614160febf3e95c5b51ffd0a0908f052wrowemost importantly users so that bug and security fixes can be quickly adopted
92adf051614160febf3e95c5b51ffd0a0908f052wrowewithout significant hardship due to user-visible changes; and continue the
92adf051614160febf3e95c5b51ffd0a0908f052wrowedevelopment process that requires ongoing redesign to correct earlier
92adf051614160febf3e95c5b51ffd0a0908f052wroweoversights and to add additional features.
92adf051614160febf3e95c5b51ffd0a0908f052wroweThe Apache HTTP Server, through version 2.0, used the Module Magic Number (MMN)
92adf051614160febf3e95c5b51ffd0a0908f052wroweto reflect API changes. This had the shortcoming of often leaving users
92adf051614160febf3e95c5b51ffd0a0908f052wrowehunting to replace binary third party modules that were now incompatible.
92adf051614160febf3e95c5b51ffd0a0908f052wroweThis also left module authors searching through the API change histories to
92adf051614160febf3e95c5b51ffd0a0908f052wrowedetermine the exact cause for the MMN change and whether their module was
92adf051614160febf3e95c5b51ffd0a0908f052wroweWith the simultaneous release of Apache 2.2-stable and Apache 2.3-development,
92adf051614160febf3e95c5b51ffd0a0908f052wrowethe Apache HTTP Server project is moving towards a more predictable stable
92adf051614160febf3e95c5b51ffd0a0908f052wrowerelease cycle, while allowing forward progress to occur without concern
92adf051614160febf3e95c5b51ffd0a0908f052wrowefor breaking the stable branch. This document explains the rationale between
92adf051614160febf3e95c5b51ffd0a0908f052wrowethe two versions and their behavior.
92adf051614160febf3e95c5b51ffd0a0908f052wroweSTABLE RELEASES, 2.{even}.{revision}
92adf051614160febf3e95c5b51ffd0a0908f052wrowe------------------------------------
92adf051614160febf3e95c5b51ffd0a0908f052wroweAll even numbered releases will be considered stable revisions.
92adf051614160febf3e95c5b51ffd0a0908f052wroweStable revisions will retain forward compatiblity to the maximum
92adf051614160febf3e95c5b51ffd0a0908f052wrowepossible extent. Features may be added during minor revisions, and
92adf051614160febf3e95c5b51ffd0a0908f052wrowefeatures may be deprecated by making appropriate notations in the
92adf051614160febf3e95c5b51ffd0a0908f052wrowedocumentation, but no features may be removed.
92adf051614160febf3e95c5b51ffd0a0908f052wroweIn essence, that implies that you can upgrade from one minor revision
92adf051614160febf3e95c5b51ffd0a0908f052wroweto the next with a minimum of trouble. In particular, this means:
92adf051614160febf3e95c5b51ffd0a0908f052wrowe * The Module API will retain forward compatibility.
92adf051614160febf3e95c5b51ffd0a0908f052wrowe It will not be necessary to update modules to work with new
92adf051614160febf3e95c5b51ffd0a0908f052wrowe revisions of the stable tree.
92adf051614160febf3e95c5b51ffd0a0908f052wrowe * The run-time configuration will be forward compatible.
92adf051614160febf3e95c5b51ffd0a0908f052wrowe No configuration changes will be necessary to work with new
92adf051614160febf3e95c5b51ffd0a0908f052wrowe revisions of the stable tree.
92adf051614160febf3e95c5b51ffd0a0908f052wrowe * Compile-time configuration will be forward compatible.
92adf051614160febf3e95c5b51ffd0a0908f052wrowe The configure command line options that work in one release
92adf051614160febf3e95c5b51ffd0a0908f052wrowe of the stable tree will also work in the next release.
92adf051614160febf3e95c5b51ffd0a0908f052wroweAs always, it will be necessary to test any new release to assure
92adf051614160febf3e95c5b51ffd0a0908f052wrowethat it works correctly with a particular configuration and a
92adf051614160febf3e95c5b51ffd0a0908f052wroweparticular set of modules, but every effort will be made to assure
92adf051614160febf3e95c5b51ffd0a0908f052wrowethat upgrades are as smooth as possible.
92adf051614160febf3e95c5b51ffd0a0908f052wroweIn addition, the following development restrictions will aid in
92adf051614160febf3e95c5b51ffd0a0908f052wrowekeeping the stable tree as safe as possible:
92adf051614160febf3e95c5b51ffd0a0908f052wrowe * No 'Experimental' modules; while it may be possible (based on API changes
92adf051614160febf3e95c5b51ffd0a0908f052wrowe required to support a given module) to load a 2.3-development module into
92adf051614160febf3e95c5b51ffd0a0908f052wrowe a 2.2-stable build of Apache, there are no guarantees. Experimental
92adf051614160febf3e95c5b51ffd0a0908f052wrowe modules will be introduced to the 2.3-development versions and either
92adf051614160febf3e95c5b51ffd0a0908f052wrowe added to 2.2-stable once they are proven and compatible, or deferred
92adf051614160febf3e95c5b51ffd0a0908f052wrowe to the 2.4-stable release if they cannot be incorporated in the current
92adf051614160febf3e95c5b51ffd0a0908f052wrowe stable release due to API change requirements.
a7ff1335befc75bdbfc0addba7306dec7bb6202ccolm * The stable subversion tree should not remain unstable at any time. Atomic
695cbdea48fde06a0da432a4e3a4a316d7751d0achrisd commits ought be used to introduce code from the development version to the
a7ff1335befc75bdbfc0addba7306dec7bb6202ccolm stable tree. At any given time a security release may be in preparation,
92adf051614160febf3e95c5b51ffd0a0908f052wrowe unbeknownst to other contributors. At any given time, testers may be
a7ff1335befc75bdbfc0addba7306dec7bb6202ccolm checking out SVN trunk to confirm that a bug has been corrected. And as
92adf051614160febf3e95c5b51ffd0a0908f052wrowe all code was well-tested in development prior to committing to the stable
92adf051614160febf3e95c5b51ffd0a0908f052wrowe tree, there is really no reason for this tree to be broken for more than
92adf051614160febf3e95c5b51ffd0a0908f052wrowe a few minutes during a lengthy commit.
92adf051614160febf3e95c5b51ffd0a0908f052wroweIn order to avoid 'skipped' release numbers in the stable releases, the
92adf051614160febf3e95c5b51ffd0a0908f052wroweRelease Manager will generally roll a release candidate (APACHE_#_#_#_RC#)
92adf051614160febf3e95c5b51ffd0a0908f052wrowetag. Release Candidate tarballs will be announced to the
92adf051614160febf3e95c5b51ffd0a0908f052wrowestable-testers@httpd.apache.org for the stable tree. Then, the participants
92adf051614160febf3e95c5b51ffd0a0908f052wrowewill vote on the quality of the proposed release tarball.
92adf051614160febf3e95c5b51ffd0a0908f052wroweThe final APACHE_#_#_# tag will not exist until the APACHE_#_#_#_RC# candidate
92adf051614160febf3e95c5b51ffd0a0908f052wrowehas passed the usual votes to release that version. Only then is the final
92adf051614160febf3e95c5b51ffd0a0908f052wrowetarball packaged, removing all -rc# designations from the version number, and
92adf051614160febf3e95c5b51ffd0a0908f052wrowetagging the tree with the release number.
92adf051614160febf3e95c5b51ffd0a0908f052wroweDEVELOPMENT RELEASES, 2.{odd}.{revision}
92adf051614160febf3e95c5b51ffd0a0908f052wrowe-----------------------------------------
92adf051614160febf3e95c5b51ffd0a0908f052wroweAll odd numbered releases designate the 'next' possible stable release,
92adf051614160febf3e95c5b51ffd0a0908f052wrowetherefore the current development version will always be one greater than
92adf051614160febf3e95c5b51ffd0a0908f052wrowethe current stable release. Work proceeds on development releases, permitting
92adf051614160febf3e95c5b51ffd0a0908f052wrowethe modification of the MMN at any time in order to correct deficiencies
92adf051614160febf3e95c5b51ffd0a0908f052wroweor shortcomings in the API. This means that modules from one development
92adf051614160febf3e95c5b51ffd0a0908f052wrowerelease to another may not be binary compatible, or may not successfully
92adf051614160febf3e95c5b51ffd0a0908f052wrowecompile without modification to accomodate the API changes.
92adf051614160febf3e95c5b51ffd0a0908f052wroweThe only 'supported' development release at any time will be the most
92adf051614160febf3e95c5b51ffd0a0908f052wrowerecently released version. Developers will not be answering bug reports
92adf051614160febf3e95c5b51ffd0a0908f052wroweof older development releases once a new release is available. It becomes
92adf051614160febf3e95c5b51ffd0a0908f052wrowethe resposibility of the reporter to use the latest development version
92adf051614160febf3e95c5b51ffd0a0908f052wroweto confirm that any issue still exists.
92adf051614160febf3e95c5b51ffd0a0908f052wroweAny new code, new API features or new ('experimental') modules may be
92adf051614160febf3e95c5b51ffd0a0908f052wrowepromoted at any time to the next stable release, by a vote of the project
92adf051614160febf3e95c5b51ffd0a0908f052wrowecontributors. This vote is based on the technical stability of the new
92adf051614160febf3e95c5b51ffd0a0908f052wrowecode and the stability of the interface. Once moved to stable, that feature
92adf051614160febf3e95c5b51ffd0a0908f052wrowecannot change for the remainder of that stable release cycle, so the vote must
92adf051614160febf3e95c5b51ffd0a0908f052wrowereflect that the final decisions on the behavior and naming of that new
92adf051614160febf3e95c5b51ffd0a0908f052wrowefeature were reached. Vetos continue to apply to this choice of introducing
92adf051614160febf3e95c5b51ffd0a0908f052wrowethe new work to the stable version.
92adf051614160febf3e95c5b51ffd0a0908f052wroweAt any given time, when the quality of changes to the development branch
92adf051614160febf3e95c5b51ffd0a0908f052wroweis considered release quality, that version may become a candidate for the
92adf051614160febf3e95c5b51ffd0a0908f052wrowenext stable release. This includes some or all of the API changes, promoting
92adf051614160febf3e95c5b51ffd0a0908f052wroweexperimental modules to stable or deprecating and eliminating older modules
92adf051614160febf3e95c5b51ffd0a0908f052wrowefrom the last stable release. All of these choices are considered by the
92adf051614160febf3e95c5b51ffd0a0908f052wroweproject as a group in the interests of promoting the stable release, so that
92adf051614160febf3e95c5b51ffd0a0908f052wroweany given change may be 'deferred' for a future release by the group, rather
92adf051614160febf3e95c5b51ffd0a0908f052wrowethan introduce unacceptable risks to adopting the next stable release.
92adf051614160febf3e95c5b51ffd0a0908f052wroweThird party module authors are strongly encouraged to test with the latest
92adf051614160febf3e95c5b51ffd0a0908f052wrowedevelopment version. This assures that the module will be ready for the next
92adf051614160febf3e95c5b51ffd0a0908f052wrowestable release, but more importantly, the author can react to shortcomings
92adf051614160febf3e95c5b51ffd0a0908f052wrowein the API early enough to warn the dev@httpd.apache.org community of the
92adf051614160febf3e95c5b51ffd0a0908f052wroweshortcomings so that they can be addressed before the stable release. The
92adf051614160febf3e95c5b51ffd0a0908f052wroweentire burden is on the module author to anticipate the needs of their module
92adf051614160febf3e95c5b51ffd0a0908f052wrowebefore the stable release is created. Once a new stable release cycle has
92adf051614160febf3e95c5b51ffd0a0908f052wrowebegun, that API will be present for the lifetime of the stable release. Any
92adf051614160febf3e95c5b51ffd0a0908f052wrowedesired changes in the stable versions must wait for inclusion into the next
92adf051614160febf3e95c5b51ffd0a0908f052wrowerelease cycle.
92adf051614160febf3e95c5b51ffd0a0908f052wroweWhen deciding to promote a development tree to being stable, a determination
92adf051614160febf3e95c5b51ffd0a0908f052wroweshould be made whether the changes since the last stable version warrant a
92adf051614160febf3e95c5b51ffd0a0908f052wrowemajor version bump. That is, if 2.2 is the current stable version and 2.3 is
92adf051614160febf3e95c5b51ffd0a0908f052wrowe'ready' to become stable, the group needs to decide if the next stable
92adf051614160febf3e95c5b51ffd0a0908f052wroweversion is 2.4 or 3.0. One suggested rule of thumb is that if it requires
92adf051614160febf3e95c5b51ffd0a0908f052wrowetoo much effort to port a module from 2.2 to 2.4, then the stable version
92adf051614160febf3e95c5b51ffd0a0908f052wroweshould be labeled 3.0.
92adf051614160febf3e95c5b51ffd0a0908f052wroweIn order to ease the burden of creating development releases, the process
92adf051614160febf3e95c5b51ffd0a0908f052wrowefor packaging a development releases is less formal than for the stable
92adf051614160febf3e95c5b51ffd0a0908f052wrowerelease. This strategy reflects the fact that while in development, versions
92adf051614160febf3e95c5b51ffd0a0908f052wroweare cheap. Development releases may be classified as alpha, beta, or GA
92adf051614160febf3e95c5b51ffd0a0908f052wroweto reflect the group's perceived stability of the tree. Development releases
92adf051614160febf3e95c5b51ffd0a0908f052wrowemay be made at any time by any committer.
92adf051614160febf3e95c5b51ffd0a0908f052wrowePlease read the following link for a more detailed description of the
92adf051614160febf3e95c5b51ffd0a0908f052wrowedevelopment release strategy: