changeset 14940:d78b92353f26

notify: rewrite user documentation

The main intent is to turn the reference help into a configuration walkthrough.
It also fix several things:
- Do not suggest to use it for commit notifications, it cannot work
- Fix notify.strip default value
- Mention that subscriptions can be setup in Mercurial configuration files
- Improve notify.strip and notify.domain documentation

--- a/hgext/notify.py	Mon Jul 25 22:19:28 2011 +0300
+++ b/hgext/notify.py	Tue Jul 26 21:30:12 2011 +0200
@@ -5,71 +5,115 @@
 # This software may be used and distributed according to the terms of the
 # GNU General Public License version 2 or any later version.
 
-'''hooks for sending email notifications at commit/push time
+'''hooks for sending email push notifications
 
-Subscriptions can be managed through a hgrc file. Default mode is to
-print messages to stdout, for testing and configuring.
+This extension let you run hooks sending email notifications when
+changesets are being pushed, from the sending or receiving side.
 
-To use, configure the notify extension and enable it in hgrc like
-this::
-
-  [extensions]
-  notify =
+First, enable the extension as explained in :hg:`help extensions`, and
+register the hook you want to run. ``incoming`` and ``outgoing`` hooks
+are run by the changesets receiver while the ``outgoing`` one is for
+the sender::
 
   [hooks]
   # one email for each incoming changeset
   incoming.notify = python:hgext.notify.hook
-  # batch emails when many changesets incoming at one time
+  # one email for all incoming changesets
   changegroup.notify = python:hgext.notify.hook
-  # batch emails when many changesets outgoing at one time (client side)
+
+  # one email for all outgoing changesets
   outgoing.notify = python:hgext.notify.hook
 
-  [notify]
-  # config items go here
-
-Required configuration items::
-
-  config = /path/to/file # file containing subscriptions
-
-Optional configuration items::
-
-  test = True            # print messages to stdout for testing
-  strip = 3              # number of slashes to strip for url paths
-  domain = example.com   # domain to use if committer missing domain
-  style = ...            # style file to use when formatting email
-  template = ...         # template to use when formatting email
-  incoming = ...         # template to use when run as incoming hook
-  outgoing = ...         # template to use when run as outgoing hook
-  changegroup = ...      # template to use when run as changegroup hook
-  maxdiff = 300          # max lines of diffs to include (0=none, -1=all)
-  maxsubject = 67        # truncate subject line longer than this
-  diffstat = True        # add a diffstat before the diff content
-  sources = serve        # notify if source of incoming changes in this list
-                         # (serve == ssh or http, push, pull, bundle)
-  merge = False          # send notification for merges (default True)
-  [email]
-  from = [e-mail]   # email address to send as if none given
-  [web]
-  baseurl = http://hgserver/... # root of hg web site for browsing commits
-
-The notify config file has same format as a regular hgrc file. It has
-two sections so you can express subscriptions in whatever way is
-handier for you.
-
-::
+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::
 
   [usersubs]
-  # key is subscriber email, value is ","-separated list of glob patterns
+  # key is subscriber email, value is a comma-separated list of glob
+  # patterns
   user@host = pattern
 
   [reposubs]
-  # key is glob pattern, value is ","-separated list of subscriber emails
+  # key is glob pattern, value is a comma-separated list of subscriber
+  # emails
   pattern = user@host
 
-Glob patterns are matched against path to repository root.
+Glob patterns are matched against absolute path to repository
+root. The subscriptions can be defined in their own file and
+referenced with::
+
+  [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 content can be tweaked with the following configuration entries:
+
+notify.test
+  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.
+
+notify.strip
+  Number of leading slashes to strip from url paths. By default, notifications
+  references repositories with their absolute path. ``notify.strip`` let 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.
 
-If you like, you can put notify config file in repository that users
-can push changes to, they can manage their own subscriptions.
+notify.style
+  Style file to use when formatting emails.
+
+notify.template
+  Template to use when formatting emails.
+
+notify.incoming
+  Template to use when run as incoming hook, override ``notify.template``.
+
+notify.outgoing
+  Template to use when run as outgoing hook, override ``notify.template``.
+
+notify.changegroup
+  Template to use when running as changegroup hook, override
+  ``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.
+
+notify.maxsubject
+  Maximum number of characters in emails subject line. Default: 67.
+
+notify.diffstat
+  Set to True to include a diffstat before diff content. Default: True.
+
+notify.merge
+  If True, send notifications for merge changesets. Default: True.
+
+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.
+
+web.baseurl
+  Root repository browsing URL to combine with repository paths when making
+  references. See also ``notify.strip``.
+
 '''
 
 from mercurial.i18n import _

--- a/tests/test-notify.t	Mon Jul 25 22:19:28 2011 +0300
+++ b/tests/test-notify.t	Tue Jul 26 21:30:12 2011 +0200
@@ -17,67 +17,111 @@
   > * = baz
   > EOF
   $ hg help notify
-  notify extension - hooks for sending email notifications at commit/push time
-  
-  Subscriptions can be managed through a hgrc file. Default mode is to print
-  messages to stdout, for testing and configuring.
+  notify extension - hooks for sending email push notifications
   
-  To use, configure the notify extension and enable it in hgrc like this:
+  This extension let you run hooks sending email notifications when changesets
+  are being pushed, from the sending or receiving side.
   
-    [extensions]
-    notify =
+  First, enable the extension as explained in "hg help extensions", and register
+  the hook you want to run. "incoming" and "outgoing" hooks are run by the
+  changesets receiver while the "outgoing" one is for the sender:
   
     [hooks]
     # one email for each incoming changeset
     incoming.notify = python:hgext.notify.hook
-    # batch emails when many changesets incoming at one time
+    # one email for all incoming changesets
     changegroup.notify = python:hgext.notify.hook
-    # batch emails when many changesets outgoing at one time (client side)
+  
+    # one email for all outgoing changesets
     outgoing.notify = python:hgext.notify.hook
   
-    [notify]
-    # config items go here
-  
-  Required configuration items:
-  
-    config = /path/to/file # file containing subscriptions
-  
-  Optional configuration items:
-  
-    test = True            # print messages to stdout for testing
-    strip = 3              # number of slashes to strip for url paths
-    domain = example.com   # domain to use if committer missing domain
-    style = ...            # style file to use when formatting email
-    template = ...         # template to use when formatting email
-    incoming = ...         # template to use when run as incoming hook
-    outgoing = ...         # template to use when run as outgoing hook
-    changegroup = ...      # template to use when run as changegroup hook
-    maxdiff = 300          # max lines of diffs to include (0=none, -1=all)
-    maxsubject = 67        # truncate subject line longer than this
-    diffstat = True        # add a diffstat before the diff content
-    sources = serve        # notify if source of incoming changes in this list
-                           # (serve == ssh or http, push, pull, bundle)
-    merge = False          # send notification for merges (default True)
-    [email]
-    from = [e-mail]   # email address to send as if none given
-    [web]
-    baseurl = http://hgserver/... # root of hg web site for browsing commits
-  
-  The notify config file has same format as a regular hgrc file. It has two
-  sections so you can express subscriptions in whatever way is handier for you.
+  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:
   
     [usersubs]
-    # key is subscriber email, value is ","-separated list of glob patterns
+    # key is subscriber email, value is a comma-separated list of glob
+    # patterns
     user@host = pattern
   
     [reposubs]
-    # key is glob pattern, value is ","-separated list of subscriber emails
+    # key is glob pattern, value is a comma-separated list of subscriber
+    # emails
     pattern = user@host
   
-  Glob patterns are matched against path to repository root.
+  Glob patterns are matched against absolute path to repository root. The
+  subscriptions can be defined in their own file and referenced with:
+  
+    [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 content can be tweaked with the following configuration entries:
+  
+  notify.test
+    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.
+  
+  notify.strip
+    Number of leading slashes to strip from url paths. By default, notifications
+    references repositories with their absolute path. "notify.strip" let 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.
   
-  If you like, you can put notify config file in repository that users can push
-  changes to, they can manage their own subscriptions.
+  notify.style
+    Style file to use when formatting emails.
+  
+  notify.template
+    Template to use when formatting emails.
+  
+  notify.incoming
+    Template to use when run as incoming hook, override "notify.template".
+  
+  notify.outgoing
+    Template to use when run as outgoing hook, override "notify.template".
+  
+  notify.changegroup
+    Template to use when running as changegroup hook, override
+    "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.
+  
+  notify.maxsubject
+    Maximum number of characters in emails subject line. Default: 67.
+  
+  notify.diffstat
+    Set to True to include a diffstat before diff content. Default: True.
+  
+  notify.merge
+    If True, send notifications for merge changesets. Default: True.
+  
+  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.
+  
+  web.baseurl
+    Root repository browsing URL to combine with repository paths when making
+    references. See also "notify.strip".
   
   no commands defined
   $ hg init a