docs/api.rst @ bdfacbcf700e default tip

API
===

hg-review takes Mercurial's approach to API stability:

* The command line interface is fairly stable and will not break often.
* File formats will not change often.
* The internal implementation may change frequently -- there are no guarantees
  of stability.

Providing a stable CLI means that (possibly non-GPL) programs can interact with
hg-review easily without fear of constant breaking.

Stable file formats mean that older versions of hg-review will be able to work
with review data from newer versions (albeit with reduced functionality).

*Not* providing a stable internal implementation allows hg-review's code to be
kept clean and elegant. It means that Python programs will needs to use
subprocesses to avoid breaking, but this is a tradeoff that the author feels is
worth making.

Data Repository Layout
----------------------

The structure of hg-review's data repository looks like this::

    your-project/
    |
    +-- .hg/
    |   |
    |   +-- review
    |   |   |
    |   |   +-- {{ changeset hash }}
    |   |   |   |
    |   |   |   +-- .exists
    |   |   |   |
    |   |   |   +-- comments
    |   |   |   |   |
    |   |   |   |   +-- {{ comment hash }}
    |   |   |   |   |
    |   |   |   |   `-- other comments...
    |   |   |   |
    |   |   |   +-- signoffs
    |   |   |       |
    |   |   |       +-- {{ signoff hash }}
    |   |   |       |
    |   |   |       `-- other signoffs ...
    |   |   |
    |   |   `-- other changesets ...
    |   |
    |   `-- other files ...
    |
    `-- other files ...

All review data for a changeset is stored in::

    .hg/review/{{ changeset hash }}/

A ``.exists`` file is included in that directory when code review for
that changeset is initialized. This allows us to check if a given changeset has
been initialized for code review very quickly.

Comments for a changeset are stored in::

    .hg/review/{{ changeset hash }}/comments/{{ comment hash }}

Signoffs for a changeset are stored in::

    .hg/review/{{ changeset hash }}/signoffs/{{ signoff hash }}

File Formats
------------

hg-review's file format is (fairly) stable and is designed to be easily parsed
to enable export to other code review systems.

Comment and signoff files are stored as JSON. The files are indented four
spaces per level to make them more human-readable.

``.exists`` Files
'''''''''''''''''

The ``.exists`` file is always empty. It simply exists to make looking up
whether a given changeset has been initialized faster. It may go away in the
future -- do not depend on it.

Comment Files
'''''''''''''

Here is a sample comment file::

    {
        "author": "Steve Losh <steve@stevelosh.com>", 
        "file": [
            "reykjavi\u0301k.txt", 
            "cmV5YWphdmnMgWsudHh0"
        ], 
        "hgdate": "Mon Jul 12 23:55:51 2010 -0400", 
        "lines": [
            0
        ], 
        "message": "Sample.", 
        "node": "0e987f91e9b6628b26a30c5d00668a15fae8f22f", 
        "style": "markdown"
    }

Comment files have some or all of the following fields:

``author``
    The Mercurial username of the person that added this comment.

``file``
    A list of two strings. The first string is a (JSON-encoded) representation
    of the UTF-8 filename. The second string is a base64 encoded version of the
    actual bytes of the filename (which is what Mercurial gives and expects to
    receive internally). If this is a review-level comment both strings will be
    blank.

``hgdate``
    The date and time the comment was added (or last edited).

``lines``
    A list of integers representing the lines of the file that this comment
    applies to. If this is a file-level or review-level comment the list will
    be empty.

``message``
    A string representing the raw comment message.

``node``
    A string representing the hash of the changset this comment belongs to, for
    easy lookup later.

``style``
    A string representing the style of this comment -- this will be
    ``markdown`` for Markdown comments and blank for plain-text comments. More
    styles may be added in the future.

Signoff Files
'''''''''''''

Here is a sample signoff file::

    {
        "author": "Steve Losh <steve@stevelosh.com>", 
        "hgdate": "Tue Jul 13 00:16:00 2010 -0400", 
        "message": "Sample.", 
        "node": "0e987f91e9b6628b26a30c5d00668a15fae8f22f", 
        "opinion": "yes", 
        "style": "markdown"
    }

Signoff files have some or all of the following fields:

``author``
    The Mercurial username of the person that added this comment.

``hgdate``
    The date and time the comment was added (or last edited).

``message``
    A string representing the raw comment message.

``node``
    A string representing the hash of the changset this comment belongs to, for
    easy lookup later.

``opinion``
    A string representing the signoff opinion. This will be ``yes``, ``no``, or
    a blank string (for a neutral signoff).

``style``
    A string representing the style of this comment -- this will be
    ``markdown`` for Markdown comments and blank for plain-text comments. More
    styles may be added in the future.

Command Line Interface
----------------------

hg-review's command line interface is (fairly) stable. If you want to interact
with review data for a repository this is the safest method to use.

See the :doc:`command line interface documentation </cli>` for more details.

Internal Python API
-------------------

hg-review's internal Python implementation is *not* stable. It may change at
any time. Relying on it virtually guarantees your application will break at
some point.

For a more stable API you should use the command line interface.

The Python API will be documented later, but is not a high priority at the
moment because of its volatility.