review/helps.py @ 4a6d47faac16

"""Help text used by the command-line UI of hg-review.

These string are kept in a separate module to make diffs easier to read and
declutter the main extension ui module.
"""

INIT = r"""
hg review --init --remote-path PATH

Initialize code review for the current repository.

When run for the first time in a project, it will do two things:

    * Create a new Mercurial repository to hold the review data at .hg/review/

    * Create and 'hg add' a .hgreview file in the current repository. You
      will need to commit this file yourself with:
      hg commmit .hgreview -m 'Initialize code review data.'

This repository contains code review data such as comments and signoffs.
It is a normal Mercurial repository, so you can push and pull review data
to and from other clones of it to share your comments and signoffs.

The --remote-path option is required, and specifies the path where the
canonical code review data for this project will live.  This is the path
that will be cloned when someone else runs 'hg review --init' on the
project.

Examples:

    hg review --init --remote-path 'http://bitbucket.org/u/project-review'
    hg review --init --remote-path '../project-review'

"""

REVIEW = r"""
hg review [-r REV] [-U CONTEXT] [--quiet] [FILE]

Show code review information about a specific revision. Diffs of all
changed files will be shown, and the line numbers printed are the ones
that should be used with 'hg review --comment --lines LINES FILE'.

If no revision is given, the current parent of the working directory
will be shown.

The number of lines of context in diffs can be changed with the -U option.
If any FILEs are given, only those diffs will be shown. If --quiet is used
no diffs will be shown.

If --verbose is used the short identifier of each comment/signoff will
also be shown.

If --debug is used the full identifier of each comment/signoff will also
be shown.

"""

COMMENT = r"""
hg review --comment -m MESSAGE [-r REV] [-l LINES] [FILE]

If no revision is given, the current parent of the working directory
will be used.

If no FILEs are given, the comment will be attached to the changeset
as a whole.

If one or more FILEs are given but no LINES are given, the comment will
be attached to the each file as a whole.

If a FILE is given and LINES is given the comment will be attached to
those specific lines.  LINES should be a comma-separated list of line
numbers (as numbered in the output of 'hg review'), such as '3' or '2,3'

Examples:

    hg review --comment -m 'This changeset needs to go in branch X.'
    hg review --comment -m 'This file should just be deleted.' script.py
    hg review --comment -m 'Trailing whitespace!' --lines 1,2,30 utils.py

"""

SIGNOFF = r"""
hg review --signoff -m MESSAGE [--yes | --no] [-r REV] [--force]

If no revision is given, the current parent of the working directory
will be used.

The --yes and --no options can be used to indicate whether you think
the changeset is "good" or "bad".  It's up to the collaborators of each
individual project to decide exactly what that means.  If neither option
is given the signoff will be marked as "neutral".

If you've already signed off on a changeset, you can use --force to
overwrite your previous signoff with a new one.

Examples:

    hg review --signoff -m 'I do not work on this part of the code.'
    hg review --signoff --yes -m 'Thanks, this change looks good.'
    hg review --signoff --no -m 'This would break backwards compatibility!'
    hg review --signoff --yes --force -m 'Nevermind, this is fine.'

"""

CHECK = r"""
hg review --check [-r REV] [--no-nos] [--yeses NUM] [--seen]

If no revision is given, the current parent of the working directory
will be used.

Check that the changeset "passes" the given tests of review status. If no tests
are given an error is returned.

Tests are checked in order. If any tests fail the command returns a status of
1 with a message describing the failure on stderr, otherwise it returns 0 and
prints nothing.

The following tests are available:

    --no-nos ensures that there are not any "no" signoffs on the changeset.

    --yeses NUM ensures that at least NUM people have signed off as "yes" on
    the changeset.

    --seen ensures that someone has commented or signed off on the changeset,
    and can be used to make sure someone has at least taken a look at it. Note
    that a signoff of "no" will make this test succeed.

"""