Boost uses the Git version control system for its development. This allows multiple contributors to work on the libraries concurrently, while keeping track of the changes that each person makes. Git is a distributed version control system, which means each contributor has their own local copy of the entire project, including its history.
The Boost libraries are modular, and each library has its own separate repository. This makes it easier to work with the entire collection of Boost libraries.
The official Boost repositories are hosted in GitHub under the https://github.com/boostorg/ account. Each library has its own repository under this organization. For example, https://github.com/boostorg/json for Boost.Json , or https://github.com/boostorg/date_time/ for Boost.DateTime .
As with any Git-based project, you can clone the repositories, make changes, commit those changes to your local repository, and push your changes back to the server. If you want to contribute changes to the official Boost libraries, refer to Contribute to an Existing Library .
The Boost Super-project repository includes all the libraries as submodules.
In addition to the libraries, you’ll find many other repositories under
that handle other tasks, for example:
The Super-project has both master and develop branches, which operate somewhat differently than for individual libraries.
New features are added and bugs are fixed in library develop branches. When the develop branch passes its' merging criteria ( Continuous Integration , projects are built correctly, other test processes run without errors, etc.), it is merged with the library master branch.
For the Super-project, the develop and master branches are independent. Both branches track the latest changes in the corresponding library branch, for all libraries. The Super-project branches are never merged, as this strategy prevents merging. In other words, the Super-project master branch is created from the library master branches, not from the Super-project develop branch (which is primarily used for testing).
When there is a public release of Boost, it is built from the master branch after that branch has been closed to updates (refer to the Release Process ).
Usually, a submodule in the Super-project will be created for a library developer by a staff member of Boost.
Recall that, in Git, when a submodule is added to a project, the submodule references a particular commit. This means that, when developers update their sub-projects, the Super-project doesn’t get immediately updated. For this reason, there is a commit bot that runs every 15 minutes and updates the commit to which each submodule references in the Super-project. This happens for both the develop and master branches.
As you update your library, and the Super-project develop branch is updated by the commit bot, you may affect other developers. For example, if a mistake is made to the MySQL library develop branch, then it will affect the CMake module, because this module runs tests to verify that you can use MySQL via CMake.
As part of Boost testing, Continuous Integration (CI) usually clones the Super-project and any required submodules.
When testing any branch that is not master , the develop branch of the Super-project is cloned.
When you’re testing master (which could be for a release), the master branch of the Super-project is cloned.
While this cloning process is not a requirement , most libraries follow it.
If you need to look at the code for the 1.82.0 release, navigate to the relevant repo, and enter:
git checkout boost-1.82.0
Developers don’t directly create Tags under repositories, when working with Boost. Tags are created by the release scripts, both in the Super-project and the individual repos, so do not add any of your own. This differs from the usual workflow in other non-Boost projects.
Boost maintains its release versions with
, where the tag is always the
prefix followed by a
number string that matches the
string format. The string format is useful because it’s something many tools understand, and for most users who just want to find a certain Boost version, that’s enough information. However, there is a unique Boost interpretation of the string.
Boost has not to date increased its' major version number. This is reserved for when something "big" happens, not for feature improvements nor API breaks.
While library maintainers try hard not to break anything, the minor version is increased when:
Three months have passed since the last release.
New features have been added because they always are.
A few things might have been broken. Details on new features and discontinued features have to be consulted in the individual libraries' Release Notes .
number is rarely used, but will be incremented from zero if there is a need for a quick update following a scheduled release. For example,
followed less than one month after
One thing library maintainers do to mitigate problems is announce their intention to break something two releases (or six months) in advance. Some maintainers keep a parallel versioning system for their library, for example:
Ultimately though, even after checking both a library readme file, and for library announcements, some testing may be necessary to be certain of whether a breaking change occurred, or not.
The repositories use the built-in GitHub issue tracker. With Boost, users are encouraged to use the issue tracker for discussions and feature requests, as well as to report bugs and other issues.
Consider creating custom templates for your library. The goal of these templates is to ensure that contributors provide enough context and information that you, and the other library authors and maintainers, can understand and reproduce the issue, or fully understand what is being discussed.
Currently, the Boost Super-project does not use the GitHub Discussion feature. If filing an issue does not seem appropriate, users are encouraged to post on the Boost developers mailing list .
Creating an issue template in GitHub can help guide contributors to provide the necessary information when they create new issues with your library.
Here are the steps to create an issue template:
Navigate to the main page of your repository.
In the menu bar (
Pull Requests, etc.), click on
Featuressection, ensure that the
Issuescheckbox is selected.
In the section
Get organized with issue templates, click on
Set up templates.
Click on the down arrow of
Add template: select, then select
Preview and editfor your custom template. Then select the pen icon to bring up the template fields.
Give your template a descriptive name, perhaps the name of your library followed by "feature request", "performance issue", "bug report" or "discussion". Remember you can enter as many templates as you think appropriate.
Give the template a full description in the
Then add the meat of the template to the
Template content. Consider adding the following, in the form of Markdown syntax and example text, to ask your users to enter:
Boost version number
The OS, compiler, hardware they are using
A brief summary of the issue/request/discussion topic
In the case of a bug or issue:
Steps to reproduce the issue
Screenshots, error messages, output
In the case of a feature request or discussion:
Accurately describe the purpose of the request (the use case, not the implementation)
Describe what they are currently doing to address the issue
Any other relevant context or information
Optional additional itemsif they fit the purpose of the template, and perhaps add yourself as one of the
When you’re done editing, at the top right of the page, click
Commit changesand create a Pull Request to update your repo.
Once the template is added, users who create new issues in your repository can choose to use one of your templates.