# HG changeset patch # User David Champion # Date 1338293230 18000 # Node ID 0fdd8193c8b5c2bf1bbb791c04d197cdf696e45f # Parent d9238286964ee5baf8d52728a9c44968553b747d notify: various fixes to docstring Typo corrections, grammar adjustments, clarity improvements. diff -r d9238286964e -r 0fdd8193c8b5 hgext/notify.py --- a/hgext/notify.py Tue Jun 12 16:20: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@host = pattern @@ -40,17 +40,17 @@ pattern = user@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,19 @@ 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: +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 d9238286964e -r 0fdd8193c8b5 tests/test-notify.t --- a/tests/test-notify.t Tue Jun 12 16:20: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@host = pattern @@ -49,17 +51,17 @@ # emails pattern = user@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