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 command line interface documentation 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.