From stdcxx-commits-return-2152-apmail-incubator-stdcxx-commits-archive=incubator.apache.org@incubator.apache.org Tue Nov 13 03:57:12 2007 Return-Path: Delivered-To: apmail-incubator-stdcxx-commits-archive@www.apache.org Received: (qmail 22044 invoked from network); 13 Nov 2007 03:57:12 -0000 Received: from hermes.apache.org (HELO mail.apache.org) (140.211.11.2) by minotaur.apache.org with SMTP; 13 Nov 2007 03:57:12 -0000 Received: (qmail 56994 invoked by uid 500); 13 Nov 2007 03:56:59 -0000 Delivered-To: apmail-incubator-stdcxx-commits-archive@incubator.apache.org Received: (qmail 56982 invoked by uid 500); 13 Nov 2007 03:56:59 -0000 Mailing-List: contact stdcxx-commits-help@incubator.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: stdcxx-dev@incubator.apache.org Delivered-To: mailing list stdcxx-commits@incubator.apache.org Received: (qmail 56971 invoked by uid 99); 13 Nov 2007 03:56:59 -0000 Received: from nike.apache.org (HELO nike.apache.org) (192.87.106.230) by apache.org (qpsmtpd/0.29) with ESMTP; Mon, 12 Nov 2007 19:56:59 -0800 X-ASF-Spam-Status: No, hits=-100.0 required=10.0 tests=ALL_TRUSTED X-Spam-Check-By: apache.org Received: from [140.211.11.3] (HELO eris.apache.org) (140.211.11.3) by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 13 Nov 2007 03:57:50 +0000 Received: by eris.apache.org (Postfix, from userid 65534) id 776811A9832; Mon, 12 Nov 2007 19:56:40 -0800 (PST) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r594420 - /incubator/stdcxx/site/releases.html Date: Tue, 13 Nov 2007 03:56:40 -0000 To: stdcxx-commits@incubator.apache.org From: sebor@apache.org X-Mailer: svnmailer-1.0.8 Message-Id: <20071113035640.776811A9832@eris.apache.org> X-Virus-Checked: Checked by ClamAV on apache.org Author: sebor Date: Mon Nov 12 19:56:39 2007 New Revision: 594420 URL: http://svn.apache.org/viewvc?rev=594420&view=rev Log: 2007-11-12 Martin Sebor * releases.html: Incorporated feedback from the first review. (Index, Goals, Definitions, References, Compatibility, Version Policy): Added new sections. (Roles): Removed. Replaced with the new Release Manager entry of the Definitions section. (Stages): Reworked, expanded. Modified: incubator/stdcxx/site/releases.html Modified: incubator/stdcxx/site/releases.html URL: http://svn.apache.org/viewvc/incubator/stdcxx/site/releases.html?rev=594420&r1=594419&r2=594420&view=diff ============================================================================== --- incubator/stdcxx/site/releases.html (original) +++ incubator/stdcxx/site/releases.html Mon Nov 12 19:56:39 2007 @@ -1,41 +1,91 @@ - Apache C++ Standard Library Release Process + + Apache C++ Standard Library Release Process and Version Policy + -

Apache C++ Standard Library Release Process

-

Draft

-

Last Updated: $Id$

+

+
+ Apache C++ Standard Library Release Process and Version Policy +
+

+

Second Draft

+

+
+ + Last Updated: $Id$ + +
+


+ +

Index

+
    +
  1. Purpose Of This Document +
  2. Goals +
  3. Stages of the Release Process +
  4. Definitions +
  5. Version Policy +
  6. References +
+

Purpose Of This Document

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

- -

Roles During a Release

-

+ +

Goals

+
    +
  • -The project committers collectively decide when to start the release process. They decide on the Release Criteria and nominate a Release Manager from amongst themselves. 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 require the consent of all committers. +The goal of the development process is to maintain a stable code base +at all times to make it possible to start the release process at any +point in time. It should be possible to check out the head of trunk or +the head of any maintenance branch at any revision and build and use +it on any platform. -

    - +
  • +
  • + +The goal of the release process is to produce periodic stable releases +that meet the Release Criteria. The +frequency of releases isn't precisely defined but a 3 to 6 month cycle +appears desirable for maintenance releases. To maintain a high degree +of stability and compatibility, minor releases should not occur more +frequently than once every 12 to 18 months. Major releases should +occur rarely, ideally not more often than once every 5 to 10 years. + +
  • +
  • + +Large scale long term projects whose stability may fluctuate over time +and where maintaining a stable code base at all times is impractical +take place on special project or platform branches. Development on +such branches isn't subject to the same development and release +process. + +
  • +
+ +

Stages of the Release Process

  1. - Planning + Start the Release Cycle
      -
    1. Decide on Roadmap
    2. -
    3. - Decide on - Primary Target Platforms -
    4. - Decide on - Secondary Target Platforms + + Establish Release Criteria
    5. +
    6. Appoint Release Manager
  2. @@ -49,122 +99,524 @@ Feature Freeze
    1. Create a release branch
    2. -
    3. Create release candidates
    4. +
    5. Create pre-release candidates
  3. Code Freeze
      -
    1. Create a final release candidate
    2. +
    3. Create the final release candidate
    4. Vote to approve release candidate
    5. Fix issues uncovered during the vote and restart process
    -
  4. -
  5. Cut a Release
  6. + +
  7. Cut the Release
  8. +
      +
    1. Tag the Release Branch
    2. +
    3. Create Distribution
    4. +
    5. Upload Distribution to the releases directory
    6. +
    7. Update Download page
    8. +
    +
  9. Announce the Release

- -

Primary Target Platforms

+ +

Start the Release Cycle

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

- -

Secondary Target Platforms

+ + +

Establish Release Criteria

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

- -

Best Effort Platforms

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

- -

Unsupported Platforms

+ +

Release Criteria

-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:

+
    +
  • + +All issues scheduled for the release have been resolved. + +
  • +
  • + +No compilation or linker errors in the test suite (including example +programs) on Primary and Secondary target platforms. + +
  • +
  • + +No test failures, including failed assertions, on Primary Target Platforms. + +
  • +
  • + +No library build failures on Best +Effort Platforms. + +
  • +
  • + +
  • +
  • + +Any outstanding test failures on Secondary Platforms are recorded in +the form of issues in the bug tracking database. + +
  • +
+

Issue Prioritization and Scheduling

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

+ +

Version and Compatibility Policy

+

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

+
+

Definitions

+

+

+ + +

Release Manager

+

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

+ +

Primary Target Platforms

+

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

+ +

Secondary Target Platforms

+

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

+ +

Best Effort Platforms

+

+ +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, ... + +

+ +

Unsupported Platforms

+

+ +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 Branches

+

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. +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 Branches

+

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

-

Feature Freeze

+

Feature Freeze

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

-

Code Freeze

+

Code Freeze

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

- -

Release Criteria

+

Compatibility

+ + +

Source Compatibility

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

-