# HG changeset patch
# User Steve Losh <steve@stevelosh.com>
# Date 1278997528 14400
# Node ID 3d544ab012cd6f681b29c722352e0aa36ef184db
# Parent  1b682f65a464a0e42b84350b400edcc0af8f7210
docs/hacking: add an initial hacking doc

diff -r 1b682f65a464 -r 3d544ab012cd docs/hacking.rst
--- a/docs/hacking.rst	Tue Jul 13 00:32:31 2010 -0400
+++ b/docs/hacking.rst	Tue Jul 13 01:05:28 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 <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.