Return-Path:
-The purpose of this document is to describe the Apache C++ Standard Library release process and versioning policy.
+The purpose of this document is to describe the Apache C++ Standard
+Library development and release processes, and version policy. A
+Release Process is a sequence of steps that starts with deciding what
+changes should be made to the project and culminates in the distribution
+of the updated project code base to the public.
-
-
+
+
+
+
+
+
+ Index
+
+
+
Purpose Of This Document
Roles During a Release
- Goals
+
+
-A known set of platforms deemed to be the most important for the release. Typically, this is a set of combinations of compilers, operating systems, and hardware architectures, and their major versions. The set is decided based on the popularity or demand for the project on those platforms. The goal is to provide the best possible user experience on these platforms, with as few compilation or link time warnings as possible (ideally none), and with all tests passing at 100%. As an example, the set of Primary Platforms can consist of gcc 4 on Red Hat Linux 5/x86_64 and Sun Studio 12 on Solaris 10/SPARC. +A new release cycle begins automatically after a previous release +cycle has ended. There may be more than one release cycle in +progress. For example, there may be a release cycle in progress with +the goal of releasing a maintenance upgrade and another to put out a +major revision.
- --A known set of platforms to be fully supported in the release. The goal is to make the project usable on these platforms without necessarily providing an ideal user experience. No compilation or linker failures should exist on Secondary Platforms but some warnings can be expected, and not all tests need pass at 100%. All failures should be analyzed and documented in the form of issues in the bug tracking database. +At the beginning of a release cycle project committers collectively establish the +set of Release Criteria for the release, nominate a Release Manager, and decide on the set of +target platforms for the release. These steps can take place in any +order. The Release Criteria must be approved by a vote on the stdcxx-dev +list. The vote must last sufficiently long to give the majority of +committers the opportunity to participate, or at least 10 days. The +set of release criteria need not change from one release to the next.
- --A known set of platforms the project builds in some but not necessarily all configurations and is mostly usable but some features may be compromised. Possibly extensive failures in the test suite are to be expected. Not all failures need be analyzed or documented. +It should be noted that anyone, including non-committers, can +participate in establishing the release criteria or in deciding the +target platforms. For example, users who are interested in support for +a particular platform are welcome to suggest it during this stage, or +file an issue in the bug tracking database requesting such support.
- --Platforms where the project is known not to build or be usable. These may be initial target platforms to which fully porting the project turned oput to be infeasible (e.g., due to availability). +The exact set of release criteria is determined at the beginning of +each release cycle and may change. The desirable set of Release +Criteria should include the following requirements:
+-Blockers should be scheduled for the next earliest micro (patch) release provided the issue can be resolved in a forward compatible way. When no micro release is scheduled at the time a Blocker is issue filed, scheduling one should be considered. Unless the binary compatibility policy prevents resolving a Blocker, a release shouldn't go out that has Blockers filed against it. The Release Manager can negotiate a lower priority of an issue with its reporter in order to defer resolving it until later. +Issues filed against the project with the Priority +of a Blocker should be scheduled for the next earliest maintenance (or +micro) release provided the issues can be resolved in a forward +compatible way. When no maintenance release is scheduled at the time a +Blocker is issue filed, scheduling one should be considered. Unless +the binary compatibility policy prevents resolving a Blocker, a +release shouldn't go out that has Blockers filed against it. The +Release Manager can negotiate a lower priority of an issue with its +reporter in order to defer resolving it until later. + +
++ +Critical issues and regressions that aren't blockers should be +scheduled for the next earliest release whose version number allows it +(as per the version and compatibility policy). It is up to the +discretion of the Release Manager to defer issues if circumstances +necessitate it. + +
++ +All issues scheduled for a release must be either closed, resolved, or +deferred before the release can go out. + +
+ ++ +The Version and Compatibility Policy specifies a mechanism, the version identifier, and a set of rules for expressing the source and compatibility of releases of the Apache C++ Standard Library. + +
+
+
+The version identifier is defined as the string
+<major>.<minor>.<micro> or, optionally,
+<major>.<minor>.<micro>.<patch> with
+the meaning below. The version of the library can be determined during
+preprocessing after the first #include
of any library
+header by testing the _RWSTD_VER
macro which encodes the
+version number in the form of a hexadecimal constant in the form
+0xMMmmuupp
, where the letters MM
correspond
+to the major number, mm
to minor, uu
to
+micro, and pp
to patch.
-Critical issues and regressions that aren't blockers should be scheduled for the next earliest release whose version number allows it (as per the versioning and compatibilty policy). It is up to the discretion of the Release Manager to defer issues if circumstances necessitate it.
+The major number (the MM
component of the
+_RWSTD_VER
macro) starts at 1 and is incremented by one
+for each new release that is source or binary incompatible with the
+previous release. Incrementing the major number resets both the minor
+and micro numbers to 0.
+
+
+
+The minor number (the mm
component of the
+_RWSTD_VER
macro) starts at 0 and is incremented by one
+for each new release that is backward but not forward compatible with
+the previous release. Incrementing the minor number resets the micro
+number to 0.
+
+
+
+The micro number (the uu
component of the
+ _RWSTD_VER
macro) starts at 0 and is incremented by one
+ for each release that contains source code changes that are both
+ backward and forward compatible with the previous release.
+
+
+
+The optional patch number (the pp
component of the
+_RWSTD_VER
macro) is unused. It is provided for third
+party distributors of the library such as compiler vendors to make it
+possible for them to make compatible changes in their distribution of
+the library without being concerned with collisions of other
+distributions. Distributors who want to make incompatible changes are
+encouraged to change the name of the library binary and define their
+own version macro.
+
+
+
+ + ++ +The Release Manager is responsible for coordinating the stages of the +release cycle, facilitating communication among developers throughout +the process, and for guiding the release process to completion. With +the help of other committers, the Release Manager decides on the set +of features and bug fixes to be implemented in a release and on a +realistic schedule for it. Throughout the release process the Release +Manager adheres to the Release Criteria initially agreed upon by all +committers. Changes to the Release Criteria or to the set of Primary +or Secondary platforms require the consensus of all +committers. Changes to Best Effort Platforms are up the Release +Manager's discretion. When the release is done the Release Manager +makes announcements about the release on news groups and mailing list +where this information might be of interest. + +
+ ++ +A known set of platforms deemed to be the most important for the +release. Typically, this is a set of combinations of compilers, +operating systems, and hardware architectures, and their major +versions, and the available configurations of the library (such as +optimized, thread-safe, etc.) The set is decided based on the +popularity or demand for the project on those platforms. The goal is +to provide the best possible user experience on these platforms, with +as few compilation or link time warnings as possible (ideally none), +and with all tests passing at 100% in all configurations of the +library. + +
++ +As an example, the set of Primary Platforms can consist of gcc 4 on +Red Hat Linux 5/x86_64 and Sun Studio 12 on Solaris 10/SPARC. + +
+ ++ +A known set of platforms to be fully supported in the release. The +goal is to make the project usable on these platforms without +necessarily providing an ideal user experience. No compilation or +linker failures should exist on Secondary Platforms but some warnings +can be expected, and not all tests need pass at 100% in some +configurations of the library. All failures should be analyzed and +documented in the form of issues in the bug tracking database. + +
+ ++ +A known set of platforms the project builds in some but not +necessarily all configurations and is mostly usable but some features +may be compromised. Possibly extensive failures in the test suite are +to be expected. Not all failures need be analyzed or documented. + +
++ +For example, a targeted compiler that generates correct code without +optimization but has such serious problems optimizing the library code +as to render the library unusable with optimization is enabled, ... + +
+ ++ +Platforms (including individual configurations on otherwise supported +target platforms) where the project is known not to build or be +usable. These may be initial target platforms to which fully porting +the project turned out to be infeasible (e.g., due to availability).
--Development of new features and extensive/invasive bug fixes or improvements takes place either on trunk, or on platform or special project branches, or on future major release branches. These are collectively known as development branches. +Development of new features and extensive/invasive bug fixes or +improvements takes place either on trunk, or on platform or special +project branches, or on future major release branches. These are +collectively known as development branches.
--Maintenance takes place on maintenance branches. A minor release branch (e.g., the 4.2.x branch created for the 4.2.0 release) becomes a maintenance branch after the minor version is released. Since maintenance releases must be both backward and forward compatible, only bug fixes or compatible improvements can take place on maintenance branches. New features are typically not implemented on maintenance branches. +Maintenance takes place on maintenance branches. A minor release +branch (e.g., the 4.2.x +branch created for the 4.2.0 release) becomes a maintenance branch +after the minor version is released. Since maintenance releases must +be both backward and forward compatible, only bug fixes or compatible +improvements can take place on maintenance branches. New features are +typically not implemented on maintenance branches.
--When the Release Manager considers the scheduled set of new features and major bug fixes to be fully implemented and the development branch sufficiently stable he or she creates a release branch if one doesn't yet exist, and announces a Feature Freeze. It's a good idea to give a heads up on an upcoming Feature Freeze date at least two weeks in advance. After a Feature Freeze, all committers must follow the Review-Then-Commit policy on the release branch, with the Release Manager having the authority to approve or reject any or all changes. Typically, only issues discovered during the testing of the release branch should be fixed there. Other non-intrusive bug fixes might be also allowed to merged in from trunk or other branches at the discretion of the Release Manager. The Release Manager effectively owns the release branch. The Release Manager should tag the release branch at this point (e.g., as the first release candidate), and continue to do as the branch stabilizes. Changes made directly on the release branch should be merged to trunk or other branches when appropriate. Development on trunk and other branches can continue unaffected. +When the Release Manager considers the scheduled set of new features +and major bug fixes to be fully implemented and the development branch +sufficiently stable he or she creates a release branch if one doesn't +yet exist, and announces a Feature Freeze on the stdcxx-dev +list. It's a good idea to give a heads up on an upcoming Feature +Freeze date at least two weeks in advance. After a Feature Freeze, all +committers must follow the Review-Then-Commit +policy on the release branch, with the Release Manager having the +authority to approve or reject any or all changes. Typically, only +issues discovered during the testing of the release branch should be +fixed there. Other non-intrusive bug fixes might be also allowed to +merged in from trunk or other branches at the discretion of the +Release Manager. The Release Manager effectively owns the release +branch. The Release Manager should tag the release branch at this +point (e.g., as the first release candidate), and continue to do as +the branch stabilizes. Changes made directly on the release branch +should be merged to trunk or other branches when +appropriate. Development on trunk and other branches can continue +unaffected.
--After the Release Manager is satisfied that the release branch meets the Release Criteria, he or she announces a Code Freeze. It is a good idea to give a heads up on an upcoming Code Freeze date at least two weeks in advance. During a Code Freeze, only documentation and other similar changes are permitted on the release branch under the Review-Then-Commit policy. No code changes should be made, except to resolve newly uncovered release-blocking issues. When the Release Manager considers the release branch ready he or she creates the final release candidate and starts a vote to approve the release. It is the responsibility of the Release Manager to make sure that all changes made on the release branch are merged to trunk or other branches as appropriate. +After the Release Manager is satisfied that the release branch meets +the Release Criteria, he or she announces a Code Freeze on the stdcxx-dev +list. It is a good idea to give a heads up on an upcoming Code Freeze +date at least two weeks in advance. During a Code Freeze, only +documentation and other similar changes are permitted on the release +branch under the Review-Then-Commit policy. No code changes should be +made, except to resolve newly uncovered release-blocking issues. When +the Release Manager considers the release branch ready he or she +creates the final release candidate and starts a vote to approve the +release. It is the responsibility of the Release Manager to make sure +that all changes made on the release branch are merged to trunk or +other branches as appropriate.
- --The desirable set of Release Criteria should include the following requirements: +Source Compatibility, important at the source code level, +determines whether two software components in their source form are +similar enough so that any well-formed program that uses one of the +components remains well-formed when the component is replaced with the +other. Source compatible changes are those that do not require any +modification to the source code that depends on the software. Source +compatibility also implies functional compatibility, although it does +not necessarily imply binary compatibility. +
-+ Examples: + + TO DO: Add examples of source incompatible changes. + +
+ +-All issues sheduled for the release have been resolved. +Binary Compatibility is the compatibility of two releases of a +library such that one can be replaced with the other without +requiring that dependent software be recompiled. -
-No compilation or linker errors in the test suite (including example programs) on Primary and Secondary target platforms. +The binary compatibility of two releases of a shared library is +determined by the binary size and layout of symbols such as functions, +types, and objects, exposed directly or indirectly as part of the +application programming interface (API) +of the library. Binary compatibility also includes functional +compatibility, i.e., the compatibility of the behavior of the new +release with the old release. A release of a product whose API, at +the binary level (sometimes referred to as ABI) +is a superset of that of another release of the same product, and +whose behavior is compatible with that of the other release, is said +to be binary compatible with the other release. Note that with C++ +features such as templates and inline functions, it is possible for +binary incompatible changes to have no effect on the symbols exposed +by the shared library binary. -
-
+ +Adding new features to a library is not a forward compatible +change since software written to take advantage of the new features +will not function correctly or at all when the library is replaced +with another (not necessarily prior) release not containing the +features. + +
++ Examples: + + TO DO: Add examples of forward incompatible changes. + +
+ ++ +A backward compatible release makes it possible for dependent software +compiled and linked against the previous release to upgrade to the +compatible release without having to be recompiled. + +
++ +Changes involving the addition of new features such as new functions, +classes, or objects, as well as the removal of undefined behavior, +i.e., changes that have no effect on the compatibility of the new +release of the library with software that was built with the +previous release of the library, are said to be backward (or +sometimes upward) compatible. + +
+- No build failures on Best Effort Platforms. +Note that sometimes, even in technical literature, the term forward +Compatibility is misused in contexts where Backward Compatibility is +really meant. For example, Hewlett Packard documentation uses the +terms in the opposite sense. +
++ Examples: + + TO DO: Add examples of backward incompatible changes. + +
+ + ++ +The following process documents were considered during the formulation +of the Apache C++ Standard Library release guidelines. + +
+