<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Contributing — Ceres Solver</title>
<link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
<link rel="top" title="Ceres Solver" href="index.html"/>
<link rel="next" title="Version History" href="version_history.html"/>
<link rel="prev" title="Users" href="users.html"/>
<script src="_static/js/modernizr.min.js"></script>
</head>
<body class="wy-body-for-nav" role="document">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search">
<a href="index.html" class="icon icon-home"> Ceres Solver
</a>
<div class="version">
1.13
</div>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
<input type="text" name="q" placeholder="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="features.html">Why?</a></li>
<li class="toctree-l1"><a class="reference internal" href="installation.html">Installation</a></li>
<li class="toctree-l1"><a class="reference internal" href="tutorial.html">Tutorial</a></li>
<li class="toctree-l1"><a class="reference internal" href="derivatives.html">On Derivatives</a></li>
<li class="toctree-l1"><a class="reference internal" href="nnls_modeling.html">Modeling Non-linear Least Squares</a></li>
<li class="toctree-l1"><a class="reference internal" href="nnls_solving.html">Solving Non-linear Least Squares</a></li>
<li class="toctree-l1"><a class="reference internal" href="nnls_covariance.html">Covariance Estimation</a></li>
<li class="toctree-l1"><a class="reference internal" href="gradient_solver.html">General Unconstrained Minimization</a></li>
<li class="toctree-l1"><a class="reference internal" href="faqs.html">FAQS, Tips & Tricks</a></li>
<li class="toctree-l1"><a class="reference internal" href="users.html">Users</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">Contributing</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#setting-up-your-environment">Setting up your Environment</a></li>
<li class="toctree-l2"><a class="reference internal" href="#submitting-a-change">Submitting a change</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="version_history.html">Version History</a></li>
<li class="toctree-l1"><a class="reference internal" href="bibliography.html">Bibliography</a></li>
<li class="toctree-l1"><a class="reference internal" href="license.html">License</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
<nav class="wy-nav-top" role="navigation" aria-label="top navigation">
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="index.html">Ceres Solver</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="index.html">Docs</a> »</li>
<li>Contributing</li>
<li class="wy-breadcrumbs-aside">
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<div class="section" id="contributing">
<span id="chapter-contributing"></span><h1>Contributing<a class="headerlink" href="#contributing" title="Permalink to this headline">¶</a></h1>
<p>We welcome contributions to Ceres, whether they are new features, bug
fixes or tests. The Ceres <a class="reference external" href="http://groups.google.com/group/ceres-solver">mailing</a> 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.</p>
<p>We follow Google’s <a class="reference external" href="http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml">C++ Style Guide</a> and
use <a class="reference external" href="http://git-scm.com/">git</a> for version control. We use the
<a class="reference external" href="https://ceres-solver-review.googlesource.com/">Gerrit</a> 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.</p>
<p>We now describe how to set up your development environment and submit
a change list for review via Gerrit.</p>
<div class="section" id="setting-up-your-environment">
<h2>Setting up your Environment<a class="headerlink" href="#setting-up-your-environment" title="Permalink to this headline">¶</a></h2>
<ol class="arabic">
<li><p class="first">Download and configure <code class="docutils literal"><span class="pre">git</span></code>.</p>
<ul class="simple">
<li>Mac <code class="docutils literal"><span class="pre">brew</span> <span class="pre">install</span> <span class="pre">git</span></code>.</li>
<li>Linux <code class="docutils literal"><span class="pre">sudo</span> <span class="pre">apt-get</span> <span class="pre">install</span> <span class="pre">git</span></code>.</li>
<li>Windows. Download <a class="reference external" href="https://code.google.com/p/msysgit/">msysgit</a>, which includes a minimal
<a class="reference external" href="http://www.cygwin.com/">Cygwin</a> install.</li>
</ul>
</li>
<li><p class="first">Sign up for <a class="reference external" href="https://ceres-solver-review.googlesource.com/">Gerrit</a>. You will also
need to sign the Contributor License Agreement (CLA) with Google,
which gives Google a royalty-free unlimited license to use your
contributions. You retain copyright.</p>
</li>
<li><p class="first">Clone the Ceres Solver <code class="docutils literal"><span class="pre">git</span></code> repository from Gerrit.</p>
<div class="highlight-bash"><div class="highlight"><pre><span></span>git clone https://ceres-solver.googlesource.com/ceres-solver
</pre></div>
</div>
</li>
<li><p class="first">Build Ceres, following the instructions in
<a class="reference internal" href="installation.html#chapter-installation"><span class="std std-ref">Installation</span></a>.</p>
<p>On Mac and Linux, the <code class="docutils literal"><span class="pre">CMake</span></code> build will download and enable
the Gerrit pre-commit hook automatically. This pre-submit hook
creates <cite>Change-Id: ...</cite> lines in your commits.</p>
<p>If this does not work OR you are on Windows, execute the
following in the root directory of the local <code class="docutils literal"><span class="pre">git</span></code> repository:</p>
<div class="highlight-bash"><div class="highlight"><pre><span></span>curl -o .git/hooks/commit-msg https://ceres-solver-review.googlesource.com/tools/hooks/commit-msg
chmod +x .git/hooks/commit-msg
</pre></div>
</div>
</li>
<li><p class="first">Configure your Gerrit password with a <code class="docutils literal"><span class="pre">.gitcookies</span></code> which allows pushing
to Gerrit without having to enter a very long random password every time:</p>
<ul class="simple">
<li>Sign into <a class="reference external" href="http://ceres-solver-review.googlesource.com">http://ceres-solver-review.googlesource.com</a>.</li>
<li>Click <code class="docutils literal"><span class="pre">Settings</span> <span class="pre">-></span> <span class="pre">HTTP</span> <span class="pre">Password</span> <span class="pre">-></span> <span class="pre">Obtain</span> <span class="pre">Password</span></code>.</li>
<li>(maybe) Select an account for multi-login. This should be the
same as your Gerrit login.</li>
<li>Click <code class="docutils literal"><span class="pre">Allow</span> <span class="pre">access</span></code> when the page requests access to your
<code class="docutils literal"><span class="pre">git</span></code> repositories.</li>
<li>Follow the instructions from Gerrit to create a <code class="docutils literal"><span class="pre">.gitcookies</span></code> file on
your system, either in <code class="docutils literal"><span class="pre">$HOME/.gitcookies</span></code> (Mac and Linux) or
<code class="docutils literal"><span class="pre">%USERPROFILE%\.gitcookies</span></code> (Windows). Note that for Windows, please get
a recent <a class="reference external" href="https://git-scm.com/download/win">Git for Windows</a> install to
enable automatic lookup in the <code class="docutils literal"><span class="pre">%USERPROFILE%\.gitcookies</span></code>.</li>
</ul>
</li>
</ol>
</div>
<div class="section" id="submitting-a-change">
<h2>Submitting a change<a class="headerlink" href="#submitting-a-change" title="Permalink to this headline">¶</a></h2>
<ol class="arabic">
<li><p class="first">Make your changes against master or whatever branch you
like. Commit your changes as one patch. When you commit, the Gerrit
hook will add a <cite>Change-Id:</cite> line as the last line of the commit.</p>
<p>Make sure that your commit message is formatted in the <a class="reference external" href="http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html">50/72 style</a>.</p>
</li>
<li><p class="first">Push your changes to the Ceres Gerrit instance:</p>
<div class="highlight-bash"><div class="highlight"><pre><span></span>git push origin HEAD:refs/for/master
</pre></div>
</div>
<p>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.</p>
</li>
<li><p class="first">Wait for a review.</p>
</li>
<li><p class="first">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 <code class="docutils literal"><span class="pre">git</span></code> instance, <em>don’t make a new
commit</em>. Instead, update the last commit using a command like the
following:</p>
<div class="highlight-bash"><div class="highlight"><pre><span></span>git commit --amend -a
</pre></div>
</div>
<p>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.</p>
<p>Gerrit will use the <code class="docutils literal"><span class="pre">Change-Id:</span></code> to match the previous commit
with the new one. The review interface retains your original patch,
but also shows the new patch.</p>
<p>Publish your responses to the comments, and wait for a new round
of reviews.</p>
</li>
</ol>
</div>
</div>
</div>
</div>
<footer>
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
<a href="version_history.html" class="btn btn-neutral float-right" title="Version History" accesskey="n">Next <span class="fa fa-arrow-circle-right"></span></a>
<a href="users.html" class="btn btn-neutral" title="Users" accesskey="p"><span class="fa fa-arrow-circle-left"></span> Previous</a>
</div>
<hr/>
<div role="contentinfo">
<p>
© Copyright 2016 Google Inc.
</p>
</div>
</footer>
</div>
</div>
</section>
</div>
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT:'./',
VERSION:'1.13.0',
COLLAPSE_INDEX:false,
FILE_SUFFIX:'.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script type="text/javascript" src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS_HTML">
MathJax.Hub.Config({
"HTML-CSS": {
availableFonts: ["TeX"]
}
});
</script>
<script type="text/javascript" src="_static/js/theme.js"></script>
<script type="text/javascript">
jQuery(function () {
SphinxRtdTheme.StickyNav.enable();
});
</script>
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-49769510-1', 'ceres-solver.org');
ga('send', 'pageview');
</script>
</body>
</html>