hg-review/_sources/hacking.txt @ c448037d3088
chancery: Update site.
| author | Steve Losh <steve@stevelosh.com> |
|---|---|
| date | Tue, 14 Mar 2017 13:35:05 +0000 |
| parents | 8a47da7c5602 |
| children | (none) |
Hacking hg-review ================= Want to improve hg-review? Great! The easiest way is to make some changes, push them somewhere public and send a pull request on Bitbucket (or `email Steve <mailto:steve@stevelosh.com>`_). Rough Guidelines ---------------- Here's a few tips that will make hg-review's maintainer happier. Basic Coding Style '''''''''''''''''' Keep lines of code under 85 characters, unless it makes things *really* ugly. Indentation is four spaces. Tabs are evil. Commit Messages ''''''''''''''' Commit messages should start with a line like:: api: add feature X The first part is the component the change affects, like ``api``, ``cli``, ``web``, ``docs/api``, or ``guts``. ``guts`` 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. The rest of the commit message should describe the change. Tests ''''' Update the tests *in the same changeset as your change*. This makes bisection by running the test suite easier. If your changeset changes the CLI output, make sure you've read the next section and then add a test for it *in the same changeset*. If your changeset adds a new feature, add a test for it *in the same changeset*. If your changeset fixes a bug, add a test that would reproduce the bug *in the same changeset*. Backwards Compatibility ''''''''''''''''''''''' 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. 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. 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. 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. Layout ------ hg-review's basic structure looks like this:: 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 Testing ------- hg-review contains a test suite for the command line interface (and therefore the backend API as well). The tests can be run easily with nose. If you don't have node, you'll need to install it first:: pip install nose Once you've got it you can run the suite by cd'ing to the hg-review directory and running ``nosetests``. Before submitting a changeset please make sure it doesn't break any tests. If your changeset adds a new feature, add a test for it *in the same changeset*. If your changeset fixes a bug, add a test that would reproduce the bug *in the same changeset*. Documentation ------------- If you want to submit a patch, please update the documentation to reflect your change (if necessary) *in the same changeset*. The documentation is formatted as restructured text and built with Sphinx (version 0.6.7). The CSS for the documentation is written with LessCSS. If you want to update the style you should update the ``docs/hgreview/static/review.less`` file and render it to CSS. Include the changes to the ``.less`` file *and* the ``.css`` file in your changeset.