docs/source/contributing.rst

   1 .. _chapter-contributing:
   2
   3 ============
   4 Contributing
   5 ============
   6
   7 We welcome contributions to Ceres, whether they are new features, bug
   8 fixes or tests. The Ceres `mailing
   9 <http://groups.google.com/group/ceres-solver>`_ list is the best place
  10 for all development related discussions. Please consider joining
  11 it. If you have ideas on how you would like to contribute to Ceres, it
  12 is a good idea to let us know on the mailing list before you start
  13 development. We may have suggestions that will save effort when trying
  14 to merge your work into the main branch. If you are looking for ideas,
  15 please let us know about your interest and skills and we will be happy
  16 to make a suggestion or three.
  17
  18 We follow Google's `C++ Style Guide
  19 <http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml>`_ and
  20 use `git <http://git-scm.com/>`_ for version control. We use the
  21 `Gerrit <https://ceres-solver-review.googlesource.com/>`_ to collaborate and
  22 review changes to Ceres. Gerrit enables pre-commit reviews so that
  23 Ceres can maintain a linear history with clean, reviewed commits, and
  24 no merges.
  25
  26 We now describe how to set up your development environment and submit
  27 a change list for review via Gerrit.
  28
  29 Setting up your Environment
  30 ===========================
  31
  32 1. Download and configure ``git``.
  33
  34    * Mac ``brew install git``.
  35    * Linux ``sudo apt-get install git``.
  36    * Windows. Download `msysgit
  37      <https://code.google.com/p/msysgit/>`_, which includes a minimal
  38      `Cygwin <http://www.cygwin.com/>`_ install.
  39
  40 2. Sign up for `Gerrit
  41    <https://ceres-solver-review.googlesource.com/>`_. You will also
  42    need to sign the Contributor License Agreement (CLA) with Google,
  43    which gives Google a royalty-free unlimited license to use your
  44    contributions. You retain copyright.
  45
  46 3. Clone the Ceres Solver ``git`` repository from Gerrit.
  47
  48    .. code-block:: bash
  49
  50       git clone https://ceres-solver.googlesource.com/ceres-solver
  51
  52
  53 4. Build Ceres, following the instructions in
  54    :ref:`chapter-installation`.
  55
  56    On Mac and Linux, the ``CMake`` build will download and enable
  57    the Gerrit pre-commit hook automatically. This pre-submit hook
  58    creates `Change-Id: ...` lines in your commits.
  59
  60    If this does not work OR you are on Windows, execute the
  61    following in the root directory of the local ``git`` repository:
  62
  63    .. code-block:: bash
  64
  65       curl -o .git/hooks/commit-msg https://ceres-solver-review.googlesource.com/tools/hooks/commit-msg
  66       chmod +x .git/hooks/commit-msg
  67
  68 5. Configure your Gerrit password with a ``.gitcookies`` which allows pushing
  69    to Gerrit without having to enter a very long random password every time:
  70
  71    * Sign into `http://ceres-solver-review.googlesource.com
  72      <http://ceres-solver-review.googlesource.com>`_.
  73
  74    * Click ``Settings -> HTTP Password -> Obtain Password``.
  75
  76    * (maybe) Select an account for multi-login. This should be the
  77      same as your Gerrit login.
  78
  79    * Click ``Allow access`` when the page requests access to your
  80      ``git`` repositories.
  81
  82    * Follow the instructions from Gerrit to create a ``.gitcookies`` file on
  83      your system, either in ``$HOME/.gitcookies`` (Mac and Linux) or
  84      ``%USERPROFILE%\.gitcookies`` (Windows). Note that for Windows, please get
  85      a recent `Git for Windows <https://git-scm.com/download/win>`_ install to
  86      enable automatic lookup in the ``%USERPROFILE%\.gitcookies``.
  87
  88 Submitting a change
  89 ===================
  90
  91 1. Make your changes against master or whatever branch you
  92    like. Commit your changes as one patch. When you commit, the Gerrit
  93    hook will add a `Change-Id:` line as the last line of the commit.
  94
  95    Make sure that your commit message is formatted in the `50/72 style
  96    <http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html>`_.
  97
  98 2. Push your changes to the Ceres Gerrit instance:
  99
 100    .. code-block:: bash
 101
 102       git push origin HEAD:refs/for/master
 103
 104    When the push succeeds, the console will display a URL showing the
 105    address of the review. Go to the URL and add at least one of the
 106    maintainers (Sameer Agarwal, Keir Mierle, Alex Stewart or William
 107    Rucklidge) as reviewers.
 108
 109 3. Wait for a review.
 110
 111 4. Once review comments come in, address them. Please reply to each
 112    comment in Gerrit, which makes the re-review process easier. After
 113    modifying the code in your ``git`` instance, *don't make a new
 114    commit*. Instead, update the last commit using a command like the
 115    following:
 116
 117    .. code-block:: bash
 118
 119       git commit --amend -a
 120
 121    This will update the last commit, so that it has both the original
 122    patch and your updates as a single commit. You will have a chance
 123    to edit the commit message as well. Push the new commit to Gerrit
 124    as before.
 125
 126    Gerrit will use the ``Change-Id:`` to match the previous commit
 127    with the new one. The review interface retains your original patch,
 128    but also shows the new patch.
 129
 130    Publish your responses to the comments, and wait for a new round
 131    of reviews.