Super-Project Workflow

The Boost super-project uses a workflow derived from a proposal by Peter Dimov. See his ​original proposal here.

The names and approaches are based on ​Git Flow.

Workflow

This is the workflow used by Boost Release Managers for the Boost super-project.

Workflow for Boost Library Maintainers is described in Modular Boost Library Workflow Overview and using it is described in Getting Started with Modular Boost Library Maintenance.

Branches

• Branch "master": Latest Boost release.
• Branch "release/n.n.n": Release preparation branch.
• Branch "develop": automatically tracks "master" of submodules (scripted).
• Branch "latest": automatically tracks "develop" of submodules (scripted).

Caution: "develop" and "latest" are present to support the legacy testing framework. Once continuous integration and test-on-demand facilities are available, these super-project branches may no longer be needed and may disappear. Library developers and users should not depend on their continued existence.

Release preparation

The release preparation branch follows the Git Flow model. It is branched from "master" and deleted once the release is complete. Branching occurs immediately after each final release.

When a submodule does a release, the super-project's "develop" for the submodule is updated to the new version, and merged (without committing) to the release branch. Release management scripts then run local tests.

The platforms used for local tests and whether the tests run against just the submodule or all of Boost will be determined by release managers based on resources available.

If the local tests succeed, the release branch is committed and pushed to the public repository. If the local tests fail, the script will revert the changes to the local release branch and the submodule maintainer will be notified.

Simple automatic scripts will not fully deal with release spanning bugs in submodules that require reverting several merges. (I.E bug fix library 1, new feature library 2, bug fix library 3, more of new feature library 2, bug fix library 4, and then the entire library 2 new feature needs to be removed.)

The hope is that by branching for release early, so that such commits occur over time, the library maintainer will be able to fix problems like the library 2 new feature example. If not, the library maintainers always have the authority to manually revert problem changes.

Regression testing

Test runners test release branch, "develop", and "latest", in sequence.

The intent is to move to an environment where regression tests of a library's development or release branch can be run against the "master" branch of all other libraries. As we develop that ability, regression testing will evolve a great deal.

Changes from original proposal

• Branch "release/n.n.n" explicitly named.
• Releases branched from "master", per Git Flow.

Open questions

• Would release management and regression testing scripts be simpler if the name of the release development branch was fixed (e.g. "release") rather than varying (e.g. "release/1.56.0")?

Acknowledgements

Thanks to Peter Dimov for his proposal!