/docs/hacking.rst
ReStructuredText | 159 lines | 121 code | 38 blank | 0 comment | 0 complexity | 2404c9660cb19369332a106555de64af MD5 | raw file
Possible License(s): GPL-2.0, BSD-3-Clause
- 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.