# HG changeset patch # User Steve Losh # Date 1278997548 14400 # Node ID b3f631ce834e114020e05ab9760dafd168d9bf6a # Parent 1d1ba7d1338d9f3b650fdfe53c3dd26bee196740 hg-review: Update documentation. diff -r 1d1ba7d1338d -r b3f631ce834e hg-review/_sources/hacking.txt --- a/hg-review/_sources/hacking.txt Tue Jul 13 00:32:56 2010 -0400 +++ b/hg-review/_sources/hacking.txt Tue Jul 13 01:05:48 2010 -0400 @@ -1,11 +1,161 @@ 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 `_). + +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. diff -r 1d1ba7d1338d -r b3f631ce834e hg-review/hacking.html --- a/hg-review/hacking.html Tue Jul 13 00:32:56 2010 -0400 +++ b/hg-review/hacking.html Tue Jul 13 01:05:48 2010 -0400 @@ -47,14 +47,136 @@

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

+

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.

@@ -67,6 +189,13 @@

Table Of Contents