docs/source/contributing.rst

.. _chapter-contributing:

============
Contributing
============

We welcome contributions to Ceres, whether they are new features, bug
fixes or tests. The Ceres `mailing
<http://groups.google.com/group/ceres-solver>`_ 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
<https://google.github.io/styleguide/cppguide.html>`_ and
use `git <http://git-scm.com/>`_ for version control. We use the
`Gerrit <https://ceres-solver-review.googlesource.com/>`_ 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
     <https://code.google.com/p/msysgit/>`_, which includes a minimal
     `Cygwin <http://www.cygwin.com/>`_ install.

2. Sign up for `Gerrit
   <https://ceres-solver-review.googlesource.com/>`_. You will also need to
   `sign the Contributor License Agreement (CLA)
   <https://opensource.google.com/docs/cla/#sign>`_ 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.

   .. code-block:: bash

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


4. Build Ceres, following the instructions in
   :ref:`chapter-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:

   .. code-block:: bash

      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
     <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 <https://git-scm.com/download/win>`_ 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 <https://superuser.com/a/1505297/1141693>`_.

   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
   <http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html>`_.

2. Push your changes to the Ceres Gerrit instance:

   .. code-block:: bash

      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.

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:

   .. code-block:: bash

      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.