1.. _chapter-contributing:
2
3============
4Contributing
5============
6
7We welcome contributions to Ceres, whether they are new features, bug
8fixes or tests. The Ceres `mailing
9<http://groups.google.com/group/ceres-solver>`_ list is the best place
10for all development related discussions. Please consider joining
11it. If you have ideas on how you would like to contribute to Ceres, it
12is a good idea to let us know on the mailing list before you start
13development. We may have suggestions that will save effort when trying
14to merge your work into the main branch. If you are looking for ideas,
15please let us know about your interest and skills and we will be happy
16to make a suggestion or three.
17
18We follow Google's `C++ Style Guide
19<http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml>`_ and
20use `git <http://git-scm.com/>`_ for version control. We use the
21`Gerrit <https://ceres-solver-review.googlesource.com/>`_ to collaborate and
22review changes to Ceres. Gerrit enables pre-commit reviews so that
23Ceres can maintain a linear history with clean, reviewed commits, and
24no merges.
25
26We now describe how to set up your development environment and submit
27a change list for review via Gerrit.
28
29Setting up your Environment
30===========================
31
321. 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
402. 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
463. 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
534. Build Ceres, following the instructions in
54   :ref:`chapter-building`.
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
685. Configure your Gerrit password with a ``.netrc`` (Mac and Linux)
69   or ``_netrc`` (Windows) which allows pushing to Gerrit without
70   having to enter a very long random password every time:
71
72   * Sign into `http://ceres-solver-review.googlesource.com
73     <http://ceres-solver-review.googlesource.com>`_.
74
75   * Click ``Settings -> HTTP Password -> Obtain Password``.
76
77   * (maybe) Select an account for multi-login. This should be the
78     same as your Gerrit login.
79
80   * Click ``Allow access`` when the page requests access to your
81     ``git`` repositories.
82
83   * Copy the contents of the ``netrc`` into the clipboard.
84
85     - On Mac and Linux, paste the contents into ``~/.netrc``.
86
87     - On Windows, by default users do not have a ``%HOME%``
88       setting.
89
90
91       Executing ``setx HOME %USERPROFILE%`` in a terminal will set up
92       the ``%HOME%`` environment variable persistently, and is used
93       by ``git`` to find ``%HOME%\_netrc``.
94
95       Then, create a new text file named ``_netrc`` and put it in
96       e.g. ``C:\Users\username`` where ``username`` is your user
97       name.
98
99
100Submitting a change
101===================
102
1031. Make your changes against master or whatever branch you
104   like. Commit your changes as one patch. When you commit, the Gerrit
105   hook will add a `Change-Id:` line as the last line of the commit.
106
107   Make sure that your commit message is formatted in the `50/72 style
108   <http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html>`_.
109
1102. Push your changes to the Ceres Gerrit instance:
111
112   .. code-block:: bash
113
114      git push origin HEAD:refs/for/master
115
116   When the push succeeds, the console will display a URL showing the
117   address of the review. Go to the URL and add atleast one of the
118   maintainers (Sameer Agarwal, Keir Mierle, or Alex Stewart) as reviewers.
119
1203. Wait for a review.
121
1224. Once review comments come in, address them. Please reply to each
123   comment in Gerrit, which makes the re-review process easier. After
124   modifying the code in your ``git`` instance, *don't make a new
125   commit*. Instead, update the last commit using a command like the
126   following:
127
128   .. code-block:: bash
129
130      git commit --amend -a
131
132   This will update the last commit, so that it has both the original
133   patch and your updates as a single commit. You will have a chance
134   to edit the commit message as well. Push the new commit to Gerrit
135   as before.
136
137   Gerrit will use the ``Change-Id:`` to match the previous commit
138   with the new one. The review interface retains your original patch,
139   but also shows the new patch.
140
141   Publish your responses to the comments, and wait for a new round
142   of reviews.
143