1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
|
.. _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.
|
