review/helps.py @ 9b3fda6ad1df

"""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"""
USAGE: hg review --init --remote-path PATH

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"""
USAGE: hg review [-r REV] [-U CONTEXT] [--quiet] [FILE]

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

Diffs of all changed files will be shown with comments inline. The line numbers
printed are the ones that should be used with ``hg review --comment --lines
LINES FILE``.

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"""
USAGE: hg review --comment [-m MESSAGE] [--mdown] [-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 are 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``.

If ``--mdown`` is used the comment text will be interpreted as Markdown.

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"""
USAGE: hg review --signoff [-m MESSAGE] [--mdown] [--yes | --no] [-r REV]

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 ``--mdown`` is used the signoff message text will be interpreted as Markdown.

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!'

"""

CHECK = r"""
USAGE: 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.

"""

WEB = r"""
USAGE: hg review --web [--read-only] [--allow-anon] [--address ADDRESS] [--port PORT]

Start the web interface on the given address and port.

Visit http://localhost:8080/ (replace the port number if you specified
a different port) in a modern browser of your choice to use the web interface.

Use ``Ctrl+C`` to stop the interface.

If ``--read-only`` is given the interface will be read-only: comments,
signoffs, pushes and pulls will be disabled. This is useful when you want to
show the data to someone but do not want them to be able to add data in your
name.

If ``--allow-anon`` is given users of the web interface will be able to add
comments even if ``--read-only`` is given. The username for these comments will
be set to an anonymous username.

If ``--address`` is given the web interface will listen on the given address
instead of the default ``127.0.0.1``. It can be useful to specify ``0.0.0.0``
when you want to allow another machine to view the interface, but **be
careful** because this will allow other people to add comments and signoffs in
your name unless you use the ``--read-only`` and/or ``--allow-anon`` options.

If ``--port`` is given the web interface will listen on the given port.

"""

EDIT = r"""
USAGE: hg review --edit IDENTIFIER [--yes | --no] [-m MESSAGE] [-l LINES] [--mdown] [FILE]

Edit the comment or changeset with the given identifier.

You can find the identifier of the item you would like to edit by running ``hg
review --verbose`` to display identifiers.

Any other options given (such as ``--message``, ``--yes`` or filenames) will
replace the content of the item you edit.

Examples::

    hg review --edit aaabbb111333 -m "This is fine."
    hg review --edit aaabbb111333 -m "These lines are bad." -l 2,3,4
    hg review --edit aaabbb111333 --no -m "I've changed my mind, this is bad."

"""