Super-Project Workflow

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

Workflow

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")?

Original Proposal by Peter Dimov

To expand on what I said in a previous message, I suggest the following structure for the superproject:

• branch "latest": automatically tracks "develop" of submodules (scripted).
• branch "develop": automatically tracks "master" of submodules (scripted).
• branch "master": contains either the last release or the current release candidate.

(This naming reflects a gitflow model. An alternative would be to use the more traditional unstable/stable for latest/develop.)

Test runners test all three, in sequence.

Release preparation starts with a gitflow release branch from boostorg:develop. The release manager then runs local tests and, if necessary, applies fixes on the branch by downgrading submodules to an earlier version or asking the submodule maintainer to resolve a problem and then upgrading the submodule to the later version.

Ideally, this release branch should be tested non-locally. However, in the past switching branches for testing has proved a problem. Therefore, the procedure continues instead with:

When the release manager is satisfied with the local test results for the release branch, he merges it to master. This becomes a release candidate. If tests prove satisfactory, the release candidate is tagged as an official release and the release branch is deleted. If not, work continues on the release branch.

Acknowledgements

Thanks to Peter Dimov for his proposal!