wiki:ImprovingPractices

Version 10 (modified by Beman Dawes, 15 years ago) ( diff )

Refine repository structure based on list comments

Development and Release Practices

Introduction

Boost developers are currently reengineering development tools, workflow, and practices aimed at more timely Boost releases with less heroics required to get releases ready to ship.

This Wiki page focuses on reorganizing our development practices and repository structure, and assumes only existing tools and scripts. Other parallel efforts focus on tools and other aspects of our release process.

Objectives

  • Professional, reliable Boost releases suitable for users ranging from simple projects by individuals on up to very large multi-developer projects in large organizations.
  • Timely Boost releases on a predictable schedule, with no possibility that problems with a few libraries can delay a release of Boost as a whole.
  • The upcoming release available from the Subversion repository at all times, release-ready and including both fixes and new libraries added subsequent to the last official release. Users of this version should not have to wait for a formal release, and should not run the risk of instability associated with purely developmental branches.
  • Release preparation does not require super-human effort by the release manager, developers, or testers.
  • A stable development environment is maintained at all times, with the development of any one library decoupled from development of other libraries. In particular, there is no "wild west" syndrome where the overall development environment is unstable because the current development state of one or more individual libraries is unstable.
  • Boost subset releases are both possible and reasonably easy. For example, Spirit should be able to do a release of it and its dependencies at any time the Spirit team wishes to do so. Note: This implies many of the other objectives, and may also require changes in where Boost header files live within the directory structure. Forwarding headers or links can be used so that such a change is transparent to users.
  • release-ready criteria include not only regression test failures, but also inspection failures, tool-chain errors, configuration errors, missing files, and any other detectable errors that reduce release quality or impact development environment stability.
  • Error reporting, including pestering, does not produce false positives, such as when failure for a library is due to instability in its dependencies.
  • Boost can to scale up to an ever-larger number of libraries, and do so without the incremental weight of each new library having a negative impact on development of other libraries or on release management.

Definitions

Release-ready

A library or branch that passes all appropriate tests and inspections, and meets all other release criteria, such as documentation being up-to-date. Note that the requirements for being release-ready are transitive; if a library has dependent libraries, it isn't considered release-ready if it breaks any of those dependent libraries.

Stable

A library or branch that passes regression tests, but does not necessarily meet other release criteria.

Prerequisite library

A library other libraries are dependent upon.

Strategies

  • The starting point for each new release is the prior release.
  • Reduce the time lag between when a library developer needs fresh test results and when those results actually become available.
  • Use existing tools wherever possible, particularly the tools Boost is already using like bjam and Subversion. Avoid introducing additional complex tool chains.
  • Encourage tool maintainers to increase tool robustness.

Repository Organization

Overview: 

//svn.boost.org/svn/boost/

                       trunk

                       tags/
                          ...
                          release/
                             ...
                             1_34_1
                             1_35_0
                      
                       branches/
                          release
                          libs/
                             ...
                             python
                             serialization
                             ...

Trunk

The main development and test location.

Every effort must be made to keep prerequisite libraries stable in the main trunk, since failures in these libraries cascade into the testing of other libraries.

There is no need or obligation for non-prerequisite libraries to be stable in the main trunk, since by definition no other libraries depend on non-prerequisite libraries.

The URL for the main trunk is [source:/trunk http://svn.boost.org/svn/boost/trunk]

Release tags

These are copies of the the release branch made by the release manager, identifying the basis for generating tarballs and such. These copies are locked so that they aren't inadvertently modified.

The URLs for release candidates are in the form http://svn.boost.org/svn/boost/tags/release/RC_1_35_0_n

The URLs for final releases are in the form http://svn.boost.org/svn/boost/tags/release/1_35_0

Release branch

The release-ready branch of Boost that will become the next release. Library changes from the trunk are merged into this branch when an update for the library is release-ready.

The release branch is where release testing occurs.

The release branch is under the control of the release manager. The release manager sets the policies for when and by whom updated libraries can be merged into the release branch, and may set locks and permissions on the release branch to enforce those policies. The policies will vary at different points of time during the release cycle. The URL for the release branch is ​http://svn.boost.org/svn/boost/branches/release

Development branches

Location for speculative/experimental/future work on an individual library or set of libraries.

The URL for development branches is in the form http://svn.boost.org/svn/boost/branches/libs/library-name

Development Cycle

Developers can ensure a stable development environment by checking out [source:/release/trunk http://svn.boost.org/svn/boost/branch/release] as their working copy, and then ​switching only the library they are working with to [source:/trunk http://svn.boost.org/svn/boost/trunk] or a library specific development branch.

Merging changes from development trunk to release branch

When the next version of a library has been tested and is stable on the main trunk, and is fully release-ready, changes to it can be merged into the release trunk.

Detailed procedure for merging:

  • Verify that the library meets all release criteria. Important: Libraries must not be merged into the release trunk until they are already known to be fully release-ready.
  • Watch test results closely; Revert if merge causes any problems whatsoever.

Special case: Prerequisite libraries

Prerequisite library changes that run any risk of breaking libraries that depend on them should always be first applied and tested on a branch, and only merged into the main trunk when stable.

The rationale is that changes to the main trunk that break prerequisite libraries are a serious problem because these changes destabilize the test environment for all libraries that depend on them. This causes developers of other libraries to expend needless effort tracking down test failures that aren't their fault.

In an ideal world changes to prerequisite library branches should be tested on various platforms prior to merging into the main trunk. In the absence of test-on-demand facilities, we will have to rely on rapid test cycling and a willingness to revert changes when changes to a prerequisite library inadvertently breaks tests of other libraries.

Special case: Breaking changes to prerequisite libraries

This case will require special coordination among affected developers. Details yet to be worked out. It may simply come down to good coordination via the developers mailing list.

Testing

Both development trunk and release branch testing go on continuously, as needed, independent of when releases actually occur. Testers never have to change the repository URLs they test against.

Trunk testing

The main trunk is where most testing resources should be concentrated, since these tests are what tell developers that their library works on all tested platforms and tell the release management team that it is OK to merge a library into the release branch.

Release branch testing

In theory, it should not be necessary to test the release branch at all, since everything merged into it should already be known to be release-ready.

In practice, the release criteria platform/compiler combinations at least must be tested on the release branch. A single reliable test runner for each release criteria platform/compiler combination may be sufficient, but that's up to the release manager to decide.

Role of the Release Manager

The release manager has the responsibility of generating a timely high-quality release.

The release manager has the authority to make all critical decisions about releases, including setting release criteria, release cycle timing, revisions of problem libraries to prior versions, and all other release related decisions.

Acknowledgments

This Wiki page is being maintained by Beman Dawes.

Although the details differ, the release model described here is similar to one ​proposed by Robert Ramey where he suggested "Each library could be developed at its own pace and schedule."

Refinements of a May, 2006, draft proposal by Beman Dawes were based on comments from Michael Fawcett, Simon Carter, Arkadiy Vertleyb, Pedro Lamarão, Robert Ramey, Anthony Williams, and Thorsten Ottosen.

Discussion during ​BoostCon 2007 between Beman Dawes, Thomas Witt, Troy Straszheim, Dave Abrahams, Eric Niebler, and Doug Gregor shaped this proposal.

Comments and corrections to this page were contributed by Stefan Seefeld, Peter Dimov, Rene Rivera, Robert Ramey, Michael Caisse, Nicola Musatti, Dave Abrahams, John Maddock, ...

Distributed under the Boost Software License, Version 1.0. (See http://www.boost.org/LICENSE_1_0.txt)

Note: See TracWiki for help on using the wiki.