Getting Started with Modular Boost Library Maintenance

This page describes the mechanics of maintaining a Boost library using Git and Modular Boost. The intended audience is developers involved in the maintenance of existing Boost libraries.

The Big Picture

Library maintenance occurs in the context of how Boost repositories are organized. Please study the Modular Boost Overview before continuing, since a Boost developer needs to be familiar with how Boost organizes its repositories.

The examples given on this page follow Boost recommended workflow practices, but keep workflow discussion simple for this introduction. If you feel you need to better understand workflow recommendations and rationale before continuing, feel free to read Modular Boost Library Workflow Overview.

Prerequisites

• A recent release of the Git command line client installed. See Getting Started with Git.
• A (free) ​GitHub account. See Getting Started with GitHub.
• A compiler and development environment installed and working smoothly.
• Modular Boost installed as described in Getting Started with Modular Boost.
• b2 in your path. That allows most of the command line examples given here to work as shown on both Windows and POSIX-like systems.

Getting started

The preferred development environment is usually for the library being worked on have a development branch checked out, while Boost super-project and other libraries remain on the master branch.

Checking out the development branch

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

cd modular-boost/libs/mylib
git branch

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

cd modular-boost/libs/mylib
git checkout develop

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:

git pull

Typical maintenance tasks

Testing locally

pushd test
b2
popd

Checking status

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:

>git status
# On branch develop
nothing to commit, working directory clean

Fix a simple bug

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, modular or not, so hopefully you are already somewhat familiar with them:

cd modular-boost/libs/mylib
git commit -a -m "my bug fix"
git push

Fix a bug using a bug-fix branch

Fixing a bug directly on the develop branch is fine, if that's the policy for the library, 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 bug-fix branch.

git checkout bugfix/complex-boo-boo

This creates the branch bugfix/complex-boo-boo, and switches to it. Incidentally, "bugfix/" is part of the name, not a directory specifier. Because we were on branch develop, develop is what the new branch is based on. Since the bug is complex, it may take some time to fix, and the developer might go through several cycles of fixes, tests, and commits.

So far, bugfix/complex-boo-boo is a private branch since it has not been pushed up to the public GitHub repo. To share work-in-progress with others or to create backup:

git push

Now the branch is public and can be seen by others.

Eventually the bug is fixed, so it is time to merge the bugfix/complex-boo-boo branch back into develop:

Start work on a new feature

Simple bugs are usually fixed on the develop branch, at least in smaller projects. There is usually no need to first create a bug-fix branch. But git developers usually create a (possibly private) branch to work on new features, since development of new features on the development branch might leave it unstable for longer that expected.

... to be supplied ...

Merge a completed feature branch to develop

Do a simple release

Do a major release

Merging to Master for the First Time

When you are ready to merge either the develop branch (or better a release branch that's forked off from develop), there's a bit of housekeeping to be done the first time (assuming your library was originally in SVN) so that future merges proceed smoothly. We're going to create a merge point between the develop and master branches so that Git knows the last point the two branches were in synch. Once we've done that Git will perform a merge by replaying the commits on develop on top of master, starting from the last known merge: in other words Git will perform the tricky stuff of figuring out what to merge for us.

Begin by navigating to the history for your library on Github, starting with branch master, for example the Config library ​can be seen here. Looking down through the commit history we can see that the last merge (In SVN land) was on October 25th 2013: make a note of that date. Now use the dropdown box to change the history to point to the develop branch, ​Config library can be seen here. As you can see there have been several commits since the date above, the last before that date was on Oct 21st, click on the commit message for that change to take you to the actual diff for that change, ​in our example here. The SHA1 for that commit is shown below and to the right of the commit message, in this case it's 67f6b934f161dc5da2039004986a14d9217afae4.

Now we'll create a merge to the specific commit, begin by changing your library to the master branch:

git checkout master

Now create a merge to the specific commit above: since we don't really want to actually change the master branch we'll use the -s ours option to avoid any conflicts:

git merge --no-ff --no-commit -s ours 67f6b934f161dc5da2039004986a14d9217afae4

You can now use git status and git diff to check for modifications, in this case there are none. Now make the commit:

git commit -am "Create first merge point for Git"

And finish off by pushing your changes to Github

git push

Then navigate to your libraries history again, and check that the merge shows up, ​our config example is here. You're now ready for "routine" merges to proceed as per Gitflow (or whatever other strategy you wish to use).