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 Building & 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 .netrc (Mac and Linux) or _netrc (Windows) 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 Password -> 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.

    • Copy the contents of the netrc into the clipboard.

      • On Mac and Linux, paste the contents into ~/.netrc.

      • On Windows, by default users do not have a %HOME% setting.

        Executing setx HOME %USERPROFILE% in a terminal will set up the %HOME% environment variable persistently, and is used by git to find %HOME%\_netrc.

        Then, create a new text file named _netrc and put it in e.g. C:\Users\username where username is your user name.

Submitting a change

  1. Make your changes against master or whatever branch you like. 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, or Alex Stewart) 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.