We welcome contributions to Ceres, whether they are new features, bug fixes or tests. The Ceres mailing list is the best place for all development related discussions. Please consider joining it. If you have ideas on how you would like to contribute to Ceres, it is a good idea to let us know on the mailing list before you start development. We may have suggestions that will save effort when trying to merge your work into the main branch. If you are looking for ideas, please let us know about your interest and skills and we will be happy to make a suggestion or three.
We follow Google’s C++ Style Guide and use git for version control. We use the Gerrit to collaborate and review changes to Ceres. Gerrit enables pre-commit reviews so that Ceres can maintain a linear history with clean, reviewed commits, and no merges.
We now describe how to set up your development environment and submit a change list for review via Gerrit.
Setting up your Environment¶
Download and configure
Sign up for Gerrit. You will also need to sign the Contributor License Agreement (CLA) with Google, which gives Google a royalty-free unlimited license to use your contributions. You retain copyright.
Clone the Ceres Solver
gitrepository from Gerrit.
git clone https://ceres-solver.googlesource.com/ceres-solver
Build Ceres, following the instructions in Installation.
On Mac and Linux, the
CMakebuild will download and enable the Gerrit pre-commit hook automatically. This pre-submit hook creates
Change-Id: ...lines in your commits.
If this does not work OR you are on Windows, execute the following in the root directory of the local
curl -o .git/hooks/commit-msg https://ceres-solver-review.googlesource.com/tools/hooks/commit-msg chmod +x .git/hooks/commit-msg
Configure your Gerrit password with a
.gitcookieswhich allows pushing to Gerrit without having to enter a very long random password every time:
Sign into http://ceres-solver-review.googlesource.com.
Settings -> HTTP Credentials -> Obtain Password.
(maybe) Select an account for multi-login. This should be the same as your Gerrit login.
Allow accesswhen the page requests access to your
Follow the instructions from Gerrit to create a
.gitcookiesfile on your system, either in
$HOME/.gitcookies(Mac and Linux) or
%USERPROFILE%\.gitcookies(Windows). Note that for Windows, please get a recent Git for Windows install to enable automatic lookup in the
brew install clang-format.
sudo apt-get install clang-format.
Windows. You can get clang-format with clang or stand-alone via npm.
You can ensure all sources files are correctly formatted before committing by manually running
clang-format -i FILENAME, by running the script
./scripts/format_all.sh, or by configuring your editor to format upon saving.
Submitting a change¶
Make your changes against master or whatever branch you like. Ensure that the changes are formatted according to
clang-format. Commit your changes as one patch. When you commit, the Gerrit hook will add a
Change-Id:line as the last line of the commit.
Make sure that your commit message is formatted in the 50/72 style.
Push your changes to the Ceres Gerrit instance:
git push origin HEAD:refs/for/master
When the push succeeds, the console will display a URL showing the address of the review. Go to the URL and add at least one of the maintainers (Sameer Agarwal, Keir Mierle, Alex Stewart or William Rucklidge) as reviewers.
Wait for a review.
Once review comments come in, address them. Please reply to each comment in Gerrit, which makes the re-review process easier. After modifying the code in your
gitinstance, don’t make a new commit. Instead, update the last commit using a command like the following:
git commit --amend -a
This will update the last commit, so that it has both the original patch and your updates as a single commit. You will have a chance to edit the commit message as well. Push the new commit to Gerrit as before.
Gerrit will use the
Change-Id:to match the previous commit with the new one. The review interface retains your original patch, but also shows the new patch.
Publish your responses to the comments, and wait for a new round of reviews.