docs/hacking.rst @ d0f41ff4e65e initial-docs

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>`_).

Here's what you need to know.

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.