Getting Started with Super-project Library Maintenance

The preferred environment library maintenance is to checkout the library’s develop branch, or some other development branch, while other Boost libraries are as defined by the Super-project master branch. This causes local tests of your library to run against master for other Boost libraries at the point in time referenced by the Super-project.

This is a more realistic test environment in than testing against the possibly unstable develop branch of other Boost libraries or against the master branch of other libraries at a different point in time than that referenced by the Super-project. Robert Ramey has advocated this approach to testing for years, and the Super-project makes this approach relatively easy and fast.

The git submodule update` will fail if it would result in uncommitted changes being overwritten.

The git submodule update may switch submodules back to the detached state, depending on the working copy’s exact situation.

See Effects of git submodule update for details.

To get more information about a submodule:

If for some reason you wanted to test against the current head of master for all libraries, disregarding the Super-project state, the git submodule update command would be changed to:

If modules are added, these should be added to your project too, which is not done by the commands above. Run:

Note that if you use the --init option, the already-initialized submodules will not be updated. You might have to run the command without --init afterwards.

You can see what branch mylib is currently on like this:

Then if you need to change the branch to a development branch such as develop, do this:

You only have to do that once; your local repo working copy will sit on the branch until it is explicitly changed by a command you give.

Of course, you don’t have to change the directory before every command, and from here on this tutorial will assume the directory has not been changed since the prior example.

If there is any possibility the branch head content in the public upstream repo has changed, you also will want to update content:

From this point on, it is assumed you have already done a cd boost-root/libs/mylib.

Unless you are 100% sure of the state of your library’s regression tests, it is a good idea to run the regression tests before making any changes to the library:

Before making changes, it is a good idea to check status. Here is what that looks like on Windows; the message you get may vary somewhat:

For simple bugs, particularly in projects with a single maintainer, it is common practice to fix bugs directly in the develop branch. Creating a test case with your favorite editor, testing the test case, fixing the bug, testing the fix, and then iterating if necessary is no different than with any programming environment.

Once the fix is complete, you then commit the fix locally and push from your local repo up to your public boostorg repo on GitHub. These same commands would be used for any Git project, so hopefully you are already somewhat familiar with them:

There are some significant disadvantages to this simple approach:

Fixing a bug directly on the develop branch is fine, if that’s the library’s policy, but if the bug is messy, multiple maintainers are involved, interruptions are expected, or other complexities are present, then it is better practice to work on the bug in a separate branch. And doing that on a hot-fix branch solves the problems mentioned at the end of the prior section.

The operational distinction between a bug-fix branch and a hot-fix branch is that a bug-fix branch is branched from develop and then at completion merged back to develop, while a hot-fix branch is branched from master and then at completion is merged to both master and develop. With either approach, the branch is deleted after it has been merged.

This creates the branch hotfix/complex-boo-boo, and switches to it. Incidentally, hotfix/ is part of the name, not a directory specifier. The new branch is based on branch master because the working copy was on branch master at the time of the branch.

Since the bug is complex, it may take some time to fix and may go through several cycles of fixes, tests, and commits.

Once the bug is fixed and a final commit is done, then it is time to merge the hotfix/complex-boo-boo branch into master and develop:

Developers are encouraged to create a (possibly private) branch to work on new features, even simple ones, since development of new features on the develop branch might leave it unstable for longer that expected. Using the Git Flow convention, the branch will be named feature/add-checksum-option.

When you create the branch, or perhaps later, you may decide the branch should be public (i.e. be present in the library’s public boostorg repo) so that you can share the branch with others or just to back it up. If so, set that up by running:

Whether or not --set-upstream origin bugfix/complex-boo-boo is actually needed depends on the branch.autosetupmerge configuration variable that isn’t discussed here. If you don’t supply --set-upstream origin bugfix/complex-boo-boo on your first push and it turns out to be needed, you will get an error message explaining that.

The usual cycle of coding, testing, commits, and pushes (if public) then begins. If other work needs to be done, a stash or commit may be done to save work-in-progress, and the working copy switched to another branch for awhile. If significant fixes or other enhancements have been made to develop over time, it may be useful to merge develop into the feature branch so that the eventual merge back to develop has less conflicts. Here is how to merge from develop to feature/add-checksum-option:

Small, simple libraries and simple releases just merge the development branch, such as develop, into master, and test like this:

If there are no test failures, tag for release and declare victory:

See Super-project Library Workflow for release tag naming conventions.

Large, complex libraries, particularly those with multiple developers working in parallel, need to use a release procedure that scales up better than the lightweight procedure. The Git Flow approach is recommended. Find out more at Super-project Library Workflow and be sure to study the examples given in Vincent Driessen’s original blog post.