This is a preliminary/temporary version of the Boost.Geometry Contribution Tutorial. This version of the Tutorial was left here for historical purposes and won't be updated. The up-to-date version can be found in the Boost.Geometry Wiki.
Contributing to Boost.Geometry
Copyright © 2014 Adam Wulkiewicz
Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at >http://www.boost.org/LICENSE_1_0.txt)
Table of Contents
- Testing the development branch of Boost.Geometry
- Fork Boost.Geometry repository
- Working with ModularBoost
- Modify the branch
- Pull request
- git (Git BASH on Windows)
- a compiler to run Boost tests - gcc, clang, Visual Studio Express, etc.
- configured GitHub account
- every step mentioned here: TryModBoost understood and tested.
Other helpful links:
Testing the development branch of Boost.Geometry
Those are the steps which must be done to check out the Boost.Geometry repository and run tests (also described here: https://svn.boost.org/trac/boost/wiki/TryModBoost#Developing).
Check out the develop branch
cd libs/geometry git checkout develop git branch -vv git pull
Run the tests
If everything works for you, you may move forward.
Fork Boost.Geometry repository
You can't work directly in the original Boost.Geometry repository, therefore you should create your fork of this library. This way you can modify the code and when the job is done send a pull request to merge your changes with the original repository.
- login on GitHub
- go to Boost.Geometry repository
- click the 'Fork' button
- choose your profile
- be happy!
More info: Forking Projects
Verify if your fork works (optional)
Go out of
clone your repository and checkout develop branch
git clone email@example.com:username/geometry geometry git checkout develop git branch -vv git pull
git log gitk
For now you should see exactly the same commits as in Boost.Geometry repository.
Working with ModularBoost
You could of course stop on the previous point and work on this local clone of the fork of Boost.Geometry however there is a catch. You won't be able to use b2 (run tests or build documentation) if the library is not inside the Boost directory. It's therefore convenient to use your fork inside modular-boost which basically means adding new remote for Boost.Geometry and using it aside the original Boost.Geometry repository.
If you did the optional steps mentioned in the section Verify if your fork works (optional), go back to the Geometry module directory
For now there is only one remote repository set for this local copy. You may check it by running
git remote -v
you should see something like this
There is one remote repository added, the original Boost.Geometry repository at boostorg/geometry
Add new remote repository
Add another remote repository, your fork, give it some memorable name
git remote add my_fork firstname.lastname@example.org:username/geometry
now after running
git remote -v
you should also see the remote you just added
Boost is using the GitFlow workflow or branching model if you like. It's because it is very well suited to collaboration and scaling the development team. Each repository using this model should contain two main branches:
- master - release-ready version of the library
- develop - development version of the library
and could contain various supporting branches for new features and hotfixes. Those supporting branches have specific purposes, there are also rules describing which branches they may originate from and which branches they may be merged with. Those issues aren't covered in this tutorial.
As a contributor you'll most likely be adding new features or fixing bugs in the development version of the library. This means that for each contribution you should create a new branch originating from the develop branch, modify it and send a pull request in order to merge it, again with the develop branch.
Create new branch for your work
Make sure you're in develop branch running
git branch -vv
you should see
Now pick a name for your new branch. Try to choose the name which doesn't already exist. To check the names of existing remote branches run
git branch -a
or check them directly on GitHub.
Lets say that you'd like to add some new feature. To reflect that, and because Boost is using the GitFlow branching model, you could name your branch
feature/example. Choosing the name for a branch is up to you since it won't be created in the original Boost.Geometry repository.
Create new local branch
git branch feature/example git checkout feature/example
push it to your fork
git push -u my_fork feature/example
This should create a remote branch for you. The
-u switch also sets up the tracking of the remote branch.
Now after running
git branch -vv
you should see
Have in mind that if you didn't use the
-u switch you wouldn't see the tracking info for your new branch.
You should also be able to see your newly created remote branch on GitHub
or while running
Modify the branch
If you plan to add a new feature, or a bugfix, or some parts for the docs, or an example, it is often wise to consult the mailing list if that is a good idea. Other people may be working on the same thing. If it is a larger feature it is good to post a sort of implementation plan to check if the feature, and the implementation, is what is expected.
A word about commits, run
and see what the commit messages convention is used.
In Boost.Geometry the commit messages should contain:
- some name of the modified part of the library in the square brackets, e.g. an algorithm name (tip: look at the namespaces and directories),
- a short title,
- an extended comment in the new lines (tip: to add more lines to the commit message use git commit without the
As it's mentioned in the GIT documentation (http://git-scm.com/book/en/Distributed-Git-Contributing-to-a-Project):
It's also a good idea to use the imperative present tense in these messages. In other words, use commands. Instead of "I added tests for" or "Adding tests for," use "Add tests for."
As you already know tests are placed in the
test/ directory. Add tests for the newly added feature and if you added new files modify the Jamfile as well.
Run the tests (assuming you're in
At the end, push your changes to the remote branch
git push my_fork feature/example
or if your local branch is tracking the remote one, just
After pushing your work you should be able to see it on GitHub.
Click "Compare and pull request" button
By default GitHub wants to request a pull to the boostorg/geometry:master branch
Change it by clicking the "Edit" button on the right side and pick develop branch
add some nice title and description
and click the "Send pull request" button.
After sending a pull request your code will be reviewed. If there are no objections your changes will be merged. Otherwise you'll see some comments under the pull request and/or under specific lines of your code. At this point it will be possible to make required changes, commit them and push to your branch. Those changes will automatically be a part of the same pull request. This procedure will be repeated until the code is ready for merging.
If you're curious how it looks like you may see one of the open or closed pull requests.