Home

Overview

Workflow

Git

GitHub

Cautions

Clone

Maintain

Patch

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

Naming rationale below explains the detailed rationale for this structure.

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 "develop" and merged with "release" once complete. If a module isn't considered ready for release (such as a new library that hasn't been fully approved) it may be reverted to an earlier version. The appropriate files are updated for the release, such as 'index.html'. It might also be necessary to update <boost/version.hpp> in Boost.Config.

When a submodule updates "master" after branching for release, the super-project's "develop" branch is updated. This is merged (Daniel James: cherry-picked? in case an earlier change was rejected) locally (without committing) to the release branch. Release management scripts then run local tests. (Daniel James: rather than not committing it might be committed locally and then reset if the tests fail).

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.

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")?
• Are new libraries that might not be ready for release added to both "develop" and "latest", or just to "latest"?
• Should we create a maintenance branch after releasing? Or just do everything on the super-project's "master" (simpler but limits making changes once the next release is in progress).
• How are changes to files in the super-project updated on both develop and latest? Probably manually for now, but when things settle it should be possible to improve this.

Naming rationale

Question: Is develop tracking master and latest tracking develop a typo or inconsistency?

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

Answer:

No, it is not. Super "develop" does track sub "master", and it does seem inconsistent, at first.

Start from the git flow workflow and the role it assigns to the "master" branch. A commit to "master" is a release, by definition. And commits to master (releases) are done by merging. Let's suppose, for simplicity, that it is "develop" that is merged to "master", and not a dedicated release branch - the latter just adds one more level of indirection.

So "master" is the last release, and "develop" is the next release (or the next next release, if a release branch is active).

Now... if a commit to the "master" branch of the super-project is a release by definition, it follows that it cannot be scripted to track submodules, right? The "master" branch of the super-project will only contain merge commits from the super-project "develop" branch (or, in practice, a super-project release branch, which will be what "develop" was at some earlier point in time.)

Consider now a submodule, smart_ptr. Applying the logic above, smart_ptr:master is the last release of smart_ptr, and smart_ptr:develop is the next release of smart_ptr. The last release of smart_ptr (smart_ptr:master) will become part of the next release of Boost (which lives on boost:develop).

Hence, boost:develop can, and should, be scripted to track smart_ptr:master.

This all falls out of the asynchronous release schedule of the submodules with respect to the super-project.

In addition, Peter proposes an additional super-project branch ("latest") that does track the submodule "develop" branches, purely for testing purposes. It's never merged to anything, no release branches are ever spawned off of it; it's just the integration test that is the equivalent of our old SVN trunk test.

It's basically a three-level architecture:

• submodule:develop
• submodule:master == super-project:develop
• super-project:master

which, if we used a single repo for all of Boost, would have been achieved with having a permanent "feature" branch per component:

• boost:feature_smart_ptr
• boost:develop
• boost:master

The workflow is more or less the same in either case - upper levels merge to lower levels when stable.

Acknowledgements

Thanks to Peter Dimov for his proposal! He also supplied the Naming rationale. Beman Dawes created and maintains this wiki page.