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.
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.
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.
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.
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:
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.
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.
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 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 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.
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.
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.
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.
A forward compatible release makes it possible for dependent software compiled and linked against the release to "downgrade" to the prior release.
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.
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.