Contributing

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

  1. Download and configure git.

    • Mac brew install git.

    • Linux sudo apt-get install git.

    • Windows. Download msysgit, which includes a minimal Cygwin install.

  2. 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.

  3. Clone the Ceres Solver git repository from Gerrit.

    git clone https://ceres-solver.googlesource.com/ceres-solver

  4. Build Ceres, following the instructions in Installation.

    On Mac and Linux, the CMake build 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 git repository:

    curl -o .git/hooks/commit-msg https://ceres-solver-review.googlesource.com/tools/hooks/commit-msg
chmod +x .git/hooks/commit-msg

  5. Configure your Gerrit password with a .gitcookies which allows pushing to Gerrit without having to enter a very long random password every time:

    • Sign into http://ceres-solver-review.googlesource.com.

    • Click Settings -> HTTP Credentials -> Obtain Password.

    • (maybe) Select an account for multi-login. This should be the same as your Gerrit login.

    • Click Allow access when the page requests access to your git repositories.

    • Follow the instructions from Gerrit to create a .gitcookies file 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 %USERPROFILE%\.gitcookies.

  6. Install clang-format.

    • Mac brew install clang-format.

    • Linux 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

  1. 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.

  2. 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, William Rucklidge or Sergiu Deitsch) as reviewers.

  3. Wait for a review.

  4. 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 git instance, 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.