Super-project Library Workflow

Workflow is the term used to describe the steps a Boost library developer follows to create, maintain, and release a library. The workflow presented here is designed for Boost’s individual libraries. The workflow for the Super-project may differ.

Git Flow

The workflow model Boost recommends is called Git Flow. It was introduced as a simple blog posting by Vincent Driessen on January 5th, 2010, that went viral and has become a widely used software engineering practice.

This workflow has arguably become so successful because it scales well from very small to very large projects, and that’s one of the reasons it is recommended (but not required) for Boost libraries.

An unusually simple, single developer library would have only the permanent develop and master branches that are required for all Boost libraries.
A more typical library would occasionally add temporary feature branches, either private or public. Feature branch names follow the feature/x model, where x names the specific feature being developed.
A larger library, particularly if it has multiple developers, would always have some active public feature branches, and at least occasionally employ release staging branches and hotfix branches. Individual developers would often use private branches.

Many Git Flow model diagrams are available online - print one out and hang it on your wall!

Command Line Tools

For those who use Git from the command line, git-flow command line tools are available to automate common operations. See git-flow wiki for more information, including installation instructions for various platforms.

Branch Names

All Boost libraries are required to have two branches:

master is always the library’s latest release. It should always be stable.
develop is always the main development branch. Whether it is always stable or not is up to the individual library.

These branches are required so that Boost release management and other scripts know the branch names.

While Boost libraries are not required to use the following branches, these naming conventions are recommended if the branches are present.

feature/descriptive-name for feature branches. For example, feature/add-roman-numeral-math.
bugfix/descriptive-name for problem fix branches of develop that will be merged back to develop after the fix. For example, bugfix/ticket-1234-error-msg-not-clear.
hotfix/descriptive-name for problem fix branches of master that will be merged back to master and also to develop after the fix. For example, hotfix/ticket-5678-crash-if-result-negative.
release/n.n.n for release staging branches. For example, release/1.56.2.

Release Names

Individual Boost libraries are free to choose their own release numbers, and these library release numbers are normally unrelated to the release numbers for the Super-project. The recommended release naming convention is the traditional three unsigned integers separated by periods (for example: 1.2.3) where:

The first integer is the major version number, with each major version, with 0 being used for initial development and 1 for the first production-usable version. A change in version number is recommended when there are breaking changes.
The middle integer is the release number, reset to 0 with each version update and otherwise increasing monotonically.
The last integer is the patch level, reset to 0 with each revision and otherwise increasing monotonically. A patch level greater than 1 indicates a so-called point releases, normally containing bug fixes but not new features.

Release Tags

A release tag is usually the library name, a hyphen, the release number, and then possibly "-beta#" or "-rc#" if applicable. Thus the second release candidate for Boost.Timer release 1.2.3 would be "timer-1.2.3-rc2".

Peter A. Bigot suggested library name prefixes for tags to avoid tag namespace pollution. Without the prefix, local tags could be overwritten.

Libraries choose their own release numbers. A simple library that does not require a complex release numbering convention might just use the date, such as "system-2014-06-02".

Rationale for Choice of Git Flow

Git Flow scales well from very small to very large projects. The same overall workflow model serves the whole spectrum of Boost libraries, even though the details differ. Git Flow has become widely known and widely used. Boost doesn’t have to pioneer a new workflow.

Aside: Deleting Merged Branches

The usual culture with Git is to delete feature branches as soon as they are merged to some other branch, and is followed by Git Flow. This approach is also recommended for Boost developers. After all, the merged-to branch keeps the commit history alive and there’s no longer any need to keep the old label around. If you delete a branch without merging it, of course, any content and commit history exclusive to that branch is lost.