hg-review/hacking.html @ ff4f055bb7f9
roul: Update site.
| author | Steve Losh <steve@stevelosh.com> |
|---|---|
| date | Sat, 07 Apr 2012 17:30:54 -0400 |
| parents | 8a47da7c5602 |
| children | (none) |
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <title>Hacking hg-review — hg-review vpre-alpha documentation</title> <link rel="stylesheet" href="_static/review.css" type="text/css" /> <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> <script type="text/javascript"> var DOCUMENTATION_OPTIONS = { URL_ROOT: '', VERSION: 'pre-alpha', COLLAPSE_MODINDEX: false, FILE_SUFFIX: '.html', HAS_SOURCE: true }; </script> <script type="text/javascript" src="_static/jquery.js"></script> <script type="text/javascript" src="_static/doctools.js"></script> <link rel="top" title="hg-review vpre-alpha documentation" href="index.html" /> <link rel="next" title="Licensing" href="licensing.html" /> <link rel="prev" title="API" href="api.html" /> </head> <body> <div class="related"> <h3>Navigation</h3> <ul> <li class="right" style="margin-right: 10px"> <a href="genindex.html" title="General Index" accesskey="I">index</a></li> <li class="right" > <a href="licensing.html" title="Licensing" accesskey="N">next</a> |</li> <li class="right" > <a href="api.html" title="API" accesskey="P">previous</a> |</li> <li><a href="index.html">hg-review vpre-alpha documentation</a> »</li> </ul> </div> <div class="document"> <div class="documentwrapper"> <div class="bodywrapper"> <div class="body"> <div class="section" id="hacking-hg-review"> <h1>Hacking hg-review<a class="headerlink" href="#hacking-hg-review" title="Permalink to this headline">¶</a></h1> <p>Want to improve hg-review? Great!</p> <p>The easiest way is to make some changes, push them somewhere public and send a pull request on Bitbucket (or <a class="reference external" href="mailto:steve%40stevelosh.com">email Steve</a>).</p> <div class="section" id="rough-guidelines"> <h2>Rough Guidelines<a class="headerlink" href="#rough-guidelines" title="Permalink to this headline">¶</a></h2> <p>Here’s a few tips that will make hg-review’s maintainer happier.</p> <div class="section" id="basic-coding-style"> <h3>Basic Coding Style<a class="headerlink" href="#basic-coding-style" title="Permalink to this headline">¶</a></h3> <p>Keep lines of code under 85 characters, unless it makes things <em>really</em> ugly.</p> <p>Indentation is four spaces. Tabs are evil.</p> </div> <div class="section" id="commit-messages"> <h3>Commit Messages<a class="headerlink" href="#commit-messages" title="Permalink to this headline">¶</a></h3> <p>Commit messages should start with a line like:</p> <div class="highlight-python"><pre>api: add feature X</pre> </div> <p>The first part is the component the change affects, like <tt class="docutils literal"><span class="pre">api</span></tt>, <tt class="docutils literal"><span class="pre">cli</span></tt>, <tt class="docutils literal"><span class="pre">web</span></tt>, <tt class="docutils literal"><span class="pre">docs/api</span></tt>, or <tt class="docutils literal"><span class="pre">guts</span></tt>.</p> <p><tt class="docutils literal"><span class="pre">guts</span></tt> is a catchall for changesets that affect everything at once – using it means that the changeset could probably be split up into separate smallet changesets.</p> <p>The rest of the commit message should describe the change.</p> </div> <div class="section" id="tests"> <h3>Tests<a class="headerlink" href="#tests" title="Permalink to this headline">¶</a></h3> <p>Update the tests <em>in the same changeset as your change</em>. This makes bisection by running the test suite easier.</p> <p>If your changeset changes the CLI output, make sure you’ve read the next section and then add a test for it <em>in the same changeset</em>.</p> <p>If your changeset adds a new feature, add a test for it <em>in the same changeset</em>.</p> <p>If your changeset fixes a bug, add a test that would reproduce the bug <em>in the same changeset</em>.</p> </div> <div class="section" id="backwards-compatibility"> <h3>Backwards Compatibility<a class="headerlink" href="#backwards-compatibility" title="Permalink to this headline">¶</a></h3> <p>hg-review’s internal implementation is not stable. Feel free to modify it however you like. Patches that clean up the code and/or enhance performance will be gladly accepted.</p> <p>hg-review’s file format is stable, but new fields may be added at any time. Removing a field or changing its format is not allowed without a very good reason. Adding an entirely new file format may be acceptable if there is a compelling reason.</p> <p>hg-review’s command line interface is stable. Adding new commands or adding new options to existing commands is fine if they prove useful. Removing commands or radically changing the default output of existing commands is not acceptable except in extreme cases.</p> <p>hg-review is currently compatible with Python 2.5+ and Mercurial 1.6+. Patches that break this compatibility will be met with a large dose of skepticism.</p> </div> </div> <div class="section" id="layout"> <h2>Layout<a class="headerlink" href="#layout" title="Permalink to this headline">¶</a></h2> <p>hg-review’s basic structure looks like this:</p> <div class="highlight-python"><pre>hg-review/ | +-- bundled/ | | | `-- ... bundled third-party modules ... | +-- contrib/ | | | `-- ... useful items not critical to hg-review's core ... | +-- docs/ | | | `-- ... the documentation (and theme) ... | +-- review/ | | | +-- static/ | | | | | `-- ... static media for the web ui ... | | | +-- templates/ | | | | | `-- ... jinja2 templates for the web ui ... | | | +-- tests/ | | | | | ` ... unit test files and accompanying utilities ... | | | +-- api.py # the core hg-review backend | | | +-- cli.py # the hg-review Mercurial extension CLI | | | +-- messages.py # messages used by the CLI | | | +-- helps.py # help text for the CLI commands | | | +-- rutil.py # useful utilities | | | `-- web.py # the web interface | +-- README.markdown | +-- LICENSE | +-- fabfile.py | `-- kick.py</pre> </div> </div> <div class="section" id="testing"> <h2>Testing<a class="headerlink" href="#testing" title="Permalink to this headline">¶</a></h2> <p>hg-review contains a test suite for the command line interface (and therefore the backend API as well).</p> <p>The tests can be run easily with nose. If you don’t have node, you’ll need to install it first:</p> <div class="highlight-python"><pre>pip install nose</pre> </div> <p>Once you’ve got it you can run the suite by cd’ing to the hg-review directory and running <tt class="docutils literal"><span class="pre">nosetests</span></tt>.</p> <p>Before submitting a changeset please make sure it doesn’t break any tests.</p> <p>If your changeset adds a new feature, add a test for it <em>in the same changeset</em>.</p> <p>If your changeset fixes a bug, add a test that would reproduce the bug <em>in the same changeset</em>.</p> </div> <div class="section" id="documentation"> <h2>Documentation<a class="headerlink" href="#documentation" title="Permalink to this headline">¶</a></h2> <p>If you want to submit a patch, please update the documentation to reflect your change (if necessary) <em>in the same changeset</em>.</p> <p>The documentation is formatted as restructured text and built with Sphinx (version 0.6.7).</p> <p>The CSS for the documentation is written with LessCSS. If you want to update the style you should update the <tt class="docutils literal"><span class="pre">docs/hgreview/static/review.less</span></tt> file and render it to CSS. Include the changes to the <tt class="docutils literal"><span class="pre">.less</span></tt> file <em>and</em> the <tt class="docutils literal"><span class="pre">.css</span></tt> file in your changeset.</p> </div> </div> </div> </div> </div> <div class="sphinxsidebar"> <div class="sphinxsidebarwrapper"> <h3><a href="index.html">Table Of Contents</a></h3> <ul> <li><a class="reference external" href="#">Hacking hg-review</a><ul> <li><a class="reference external" href="#rough-guidelines">Rough Guidelines</a><ul> <li><a class="reference external" href="#basic-coding-style">Basic Coding Style</a></li> <li><a class="reference external" href="#commit-messages">Commit Messages</a></li> <li><a class="reference external" href="#tests">Tests</a></li> <li><a class="reference external" href="#backwards-compatibility">Backwards Compatibility</a></li> </ul> </li> <li><a class="reference external" href="#layout">Layout</a></li> <li><a class="reference external" href="#testing">Testing</a></li> <li><a class="reference external" href="#documentation">Documentation</a></li> </ul> </li> </ul> <h4>Previous topic</h4> <p class="topless"><a href="api.html" title="previous chapter">API</a></p> <h4>Next topic</h4> <p class="topless"><a href="licensing.html" title="next chapter">Licensing</a></p> <h3>This Page</h3> <ul class="this-page-menu"> <li><a href="_sources/hacking.txt" rel="nofollow">Show Source</a></li> </ul> <div id="searchbox" style="display: none"> <h3>Quick search</h3> <form class="search" action="search.html" method="get"> <input type="text" name="q" size="18" /> <input type="submit" value="Go" /> <input type="hidden" name="check_keywords" value="yes" /> <input type="hidden" name="area" value="default" /> </form> <p class="searchtip" style="font-size: 90%"> Enter search terms or a module, class or function name. </p> </div> <script type="text/javascript">$('#searchbox').show(0);</script> </div> </div> <div class="clearer"></div> </div> <div class="related"> <h3>Navigation</h3> <ul> <li class="right" style="margin-right: 10px"> <a href="genindex.html" title="General Index" >index</a></li> <li class="right" > <a href="licensing.html" title="Licensing" >next</a> |</li> <li class="right" > <a href="api.html" title="API" >previous</a> |</li> <li><a href="index.html">hg-review vpre-alpha documentation</a> »</li> </ul> </div> <div class="footer"> © Copyright 2010, Steve Losh and contributors. Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 0.6.7. </div> </body> </html>