[PATCH 1 of 2] notify: various fixes to docstring
David Champion
dgc at uchicago.edu
Tue May 29 12:58:38 UTC 2012
# HG changeset patch
# User David Champion <dgc at uchicago.edu>
# Date 1338293230 18000
# Node ID 222934f53810943a6e7eb74ebd756ea8cafa810e
# Parent 2ac08d8b21aa7b6e0a062afed5a3f357ccef67f9
notify: various fixes to docstring
Typo corrections, grammar adjustments, clarity improvements.
diff -r 2ac08d8b21aa -r 222934f53810 hgext/notify.py
--- a/hgext/notify.py Tue May 22 14:37:20 2012 -0500
+++ b/hgext/notify.py Tue May 29 07:07:10 2012 -0500
@@ -7,13 +7,13 @@
'''hooks for sending email push notifications
-This extension let you run hooks sending email notifications when
-changesets are being pushed, from the sending or receiving side.
+This extension implements hooks to send email notifications when
+changesets are sent from or received by the local repository.
First, enable the extension as explained in :hg:`help extensions`, and
register the hook you want to run. ``incoming`` and ``changegroup`` hooks
-are run by the changesets receiver while the ``outgoing`` one is for
-the sender::
+are run when changesets are received, while ``outgoing`` hooks are for
+changesets sent to another repository::
[hooks]
# one email for each incoming changeset
@@ -24,13 +24,13 @@
# one email for all outgoing changesets
outgoing.notify = python:hgext.notify.hook
-Now the hooks are running, subscribers must be assigned to
-repositories. Use the ``[usersubs]`` section to map repositories to a
-given email or the ``[reposubs]`` section to map emails to a single
-repository::
+This registers the hooks. To enable notification, subscribers must
+be assigned to repositories. The ``[usersubs]`` section maps multiple
+repositories to a given recipient. The ``[reposubs]`` section maps
+multiple recipients to a single repository::
[usersubs]
- # key is subscriber email, value is a comma-separated list of glob
+ # key is subscriber email, value is a comma-separated list of repo glob
# patterns
user at host = pattern
@@ -40,17 +40,17 @@
pattern = user at host
Glob patterns are matched against absolute path to repository
-root. The subscriptions can be defined in their own file and
-referenced with::
+root.
+
+In order to place them under direct user management, ``[usersubs]`` and
+``[reposubs]`` sections may be placed in a separate ``hgrc`` file and
+incorporated by reference::
[notify]
config = /path/to/subscriptionsfile
-Alternatively, they can be added to Mercurial configuration files by
-setting the previous entry to an empty value.
-
-At this point, notifications should be generated but will not be sent until you
-set the ``notify.test`` entry to ``False``.
+Notifications will not be sent until the ``notify.test`` value is set
+to ``False``; see below.
Notifications content can be tweaked with the following configuration entries:
@@ -58,23 +58,25 @@
If ``True``, print messages to stdout instead of sending them. Default: True.
notify.sources
- Space separated list of change sources. Notifications are sent only
- if it includes the incoming or outgoing changes source. Incoming
- sources can be ``serve`` for changes coming from http or ssh,
- ``pull`` for pulled changes, ``unbundle`` for changes added by
- :hg:`unbundle` or ``push`` for changes being pushed
- locally. Outgoing sources are the same except for ``unbundle`` which
- is replaced by ``bundle``. Default: serve.
+ Space-separated list of change sources. Notifications are activated only
+ when a changeset's source is in this list. Sources may be::
+
+:``serve``: changesets received via http or ssh
+:``pull``: changesets received via ``hg pull``
+:``unbundle``: changesets received via ``hg unbundle``
+:``push``: changesets sent or received via ``hg push``
+:``bundle``: changesets sent via ``hg unbundle``
+
+ Default: serve.
notify.strip
Number of leading slashes to strip from url paths. By default, notifications
- references repositories with their absolute path. ``notify.strip`` let you
+ reference repositories with their absolute path. ``notify.strip`` lets you
turn them into relative paths. For example, ``notify.strip=3`` will change
``/long/path/repository`` into ``repository``. Default: 0.
notify.domain
- If subscribers emails or the from email have no domain set, complete them
- with this value.
+ Default email domain for sender or recipients with no explicit domain.
notify.style
Style file to use when formatting emails.
@@ -83,21 +85,21 @@
Template to use when formatting emails.
notify.incoming
- Template to use when run as incoming hook, override ``notify.template``.
+ Template to use when run as an incoming hook, overriding ``notify.template``.
notify.outgoing
- Template to use when run as outgoing hook, override ``notify.template``.
+ Template to use when run as an outgoing hook, overriding ``notify.template``.
notify.changegroup
- Template to use when running as changegroup hook, override
+ Template to use when running as a changegroup hook, overriding
``notify.template``.
notify.maxdiff
Maximum number of diff lines to include in notification email. Set to 0
- to disable the diff, -1 to include all of it. Default: 300.
+ to disable the diff, or -1 to include all of it. Default: 300.
notify.maxsubject
- Maximum number of characters in emails subject line. Default: 67.
+ Maximum number of characters in email's subject line. Default: 67.
notify.diffstat
Set to True to include a diffstat before diff content. Default: True.
@@ -109,17 +111,17 @@
If set, append mails to this mbox file instead of sending. Default: None.
notify.fromauthor
- If set, use the first committer of the changegroup for the "From" field of
- the notification mail. If not set, take the user from the pushing repo.
- Default: False.
+ If set, use the committer of the first changeset in a changegroup for
+ the "From" field of the notification mail. If not set, take the user
+ from the pushing repo. Default: False.
If set, the following entries will also be used to customize the notifications:
email.from
- Email ``From`` address to use if none can be found in generated email content.
+ Email ``From`` address to use if none can be found in the generated email content.
web.baseurl
- Root repository browsing URL to combine with repository paths when making
+ Root repository URL to combine with repository paths when making
references. See also ``notify.strip``.
'''
diff -r 2ac08d8b21aa -r 222934f53810 tests/test-notify.t
--- a/tests/test-notify.t Tue May 22 14:37:20 2012 -0500
+++ b/tests/test-notify.t Tue May 29 07:07:10 2012 -0500
@@ -19,12 +19,13 @@
$ hg help notify
notify extension - hooks for sending email push notifications
- This extension let you run hooks sending email notifications when changesets
- are being pushed, from the sending or receiving side.
+ This extension implements hooks to send email notifications when changesets
+ are sent from or received by the local repository.
First, enable the extension as explained in "hg help extensions", and register
- the hook you want to run. "incoming" and "changegroup" hooks are run by the
- changesets receiver while the "outgoing" one is for the sender:
+ the hook you want to run. "incoming" and "changegroup" hooks are run when
+ changesets are received, while "outgoing" hooks are for changesets sent to
+ another repository:
[hooks]
# one email for each incoming changeset
@@ -35,12 +36,13 @@
# one email for all outgoing changesets
outgoing.notify = python:hgext.notify.hook
- Now the hooks are running, subscribers must be assigned to repositories. Use
- the "[usersubs]" section to map repositories to a given email or the
- "[reposubs]" section to map emails to a single repository:
+ This registers the hooks. To enable notification, subscribers must be assigned
+ to repositories. The "[usersubs]" section maps multiple repositories to a
+ given recipient. The "[reposubs]" section maps multiple recipients to a single
+ repository:
[usersubs]
- # key is subscriber email, value is a comma-separated list of glob
+ # key is subscriber email, value is a comma-separated list of repo glob
# patterns
user at host = pattern
@@ -49,17 +51,17 @@
# emails
pattern = user at host
- Glob patterns are matched against absolute path to repository root. The
- subscriptions can be defined in their own file and referenced with:
+ Glob patterns are matched against absolute path to repository root.
+
+ In order to place them under direct user management, "[usersubs]" and
+ "[reposubs]" sections may be placed in a separate "hgrc" file and incorporated
+ by reference:
[notify]
config = /path/to/subscriptionsfile
- Alternatively, they can be added to Mercurial configuration files by setting
- the previous entry to an empty value.
-
- At this point, notifications should be generated but will not be sent until
- you set the "notify.test" entry to "False".
+ Notifications will not be sent until the "notify.test" value is set to
+ "False"; see below.
Notifications content can be tweaked with the following configuration entries:
@@ -67,22 +69,25 @@
If "True", print messages to stdout instead of sending them. Default: True.
notify.sources
- Space separated list of change sources. Notifications are sent only if it
- includes the incoming or outgoing changes source. Incoming sources can be
- "serve" for changes coming from http or ssh, "pull" for pulled changes,
- "unbundle" for changes added by "hg unbundle" or "push" for changes being
- pushed locally. Outgoing sources are the same except for "unbundle" which is
- replaced by "bundle". Default: serve.
+ Space-separated list of change sources. Notifications are activated only
+ when a changeset's source is in this list. Sources may be:
+
+ "serve" changesets received via http or ssh
+ "pull" changesets received via "hg pull"
+ "unbundle" changesets received via "hg unbundle"
+ "push" changesets sent or received via "hg push"
+ "bundle" changesets sent via "hg unbundle"
+
+ Default: serve.
notify.strip
Number of leading slashes to strip from url paths. By default, notifications
- references repositories with their absolute path. "notify.strip" let you
+ reference repositories with their absolute path. "notify.strip" lets you
turn them into relative paths. For example, "notify.strip=3" will change
"/long/path/repository" into "repository". Default: 0.
notify.domain
- If subscribers emails or the from email have no domain set, complete them
- with this value.
+ Default email domain for sender or recipients with no explicit domain.
notify.style
Style file to use when formatting emails.
@@ -91,21 +96,21 @@
Template to use when formatting emails.
notify.incoming
- Template to use when run as incoming hook, override "notify.template".
+ Template to use when run as an incoming hook, overriding "notify.template".
notify.outgoing
- Template to use when run as outgoing hook, override "notify.template".
+ Template to use when run as an outgoing hook, overriding "notify.template".
notify.changegroup
- Template to use when running as changegroup hook, override
+ Template to use when running as a changegroup hook, overriding
"notify.template".
notify.maxdiff
Maximum number of diff lines to include in notification email. Set to 0 to
- disable the diff, -1 to include all of it. Default: 300.
+ disable the diff, or -1 to include all of it. Default: 300.
notify.maxsubject
- Maximum number of characters in emails subject line. Default: 67.
+ Maximum number of characters in email's subject line. Default: 67.
notify.diffstat
Set to True to include a diffstat before diff content. Default: True.
@@ -117,19 +122,20 @@
If set, append mails to this mbox file instead of sending. Default: None.
notify.fromauthor
- If set, use the first committer of the changegroup for the "From" field of
- the notification mail. If not set, take the user from the pushing repo.
- Default: False.
+ If set, use the committer of the first changeset in a changegroup for the
+ "From" field of the notification mail. If not set, take the user from the
+ pushing repo. Default: False.
If set, the following entries will also be used to customize the
notifications:
email.from
- Email "From" address to use if none can be found in generated email content.
+ Email "From" address to use if none can be found in the generated email
+ content.
web.baseurl
- Root repository browsing URL to combine with repository paths when making
- references. See also "notify.strip".
+ Root repository URL to combine with repository paths when making references.
+ See also "notify.strip".
no commands defined
$ hg init a
More information about the Mercurial-devel
mailing list