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-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 68 5. 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 100 Submitting a change 101 =================== 102 103 1. 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 110 2. 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 120 3. Wait for a review. 121 122 4. 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
