Add README for a git_multimail.py plugin

Since supporting git_multimail.py is quite complex, this README
provides documentation.  Eventually it might do well to be converted
to a chapter in the admin manual.

1 files changed, 161 insertions, 0 deletions

diff --git a/plugins/README.multimail b/plugins/README.multimail
new file mode 100644
index 0000000..1b52f7d
--- /dev/null
+++ b/plugins/README.multimail
@@ -0,0 +1,161 @@
+Using Git Multimail with Gitano
+===============================
+
+Gitano provides a plugin for use with `git_multimail.py`.  In order to use it
+a number of preparatory steps must be taken.
+
+Sysadmin responsibilities
+-------------------------
+
+In order to enable the multimail capability in Gitano the plugin must be
+installed (it will be, by default, but some distributions may put it in a
+separate package).  Also there must be a copy of `git_multimail.py` on the
+system somewhere.  It may be available in the contrib part of the distribution
+Git package, otherwise it can be acquired from:
+
+    https://git.kernel.org/pub/scm/git/git.git/plain/contrib/hooks/multimail/git_multimail.py?id=HEAD
+
+The sysadmin must become the unix user that Gitano is running as, and run the
+following command to enable the plugin `git_multimail.py`
+
+    $ git config --global gitano.multimail.location /path/to/wherever/git_multimail.py
+
+Without this setting, the multimail plugin will be entirely disabled.  The
+actual `git_multimail.py` must be executable and must have any dependencies met
+on the system.
+
+In addition, the sysadmin will want to configure things like
+`multimailhook.mailer` and associated settings such that `git_multimail.py`
+will be able to send emails out.
+
+Gitano-Admin responsibilities
+-----------------------------
+
+### Rules
+
+Once the multimail plugin is permitted to run for the site, it also needs to
+use the Gitano ACL system to check for permission to run on the given
+repository.  Note that control over which refs it runs for is independent of
+this ACL check.
+
+In order to check for permission, the multimail plugin will request, of the
+repository in question, an ACL check of the form:
+
+* `source`: `plugin_multimail`
+* `repository`: `path/to/repo`
+* `operation`: `multimail`
+* `user`: `gitano/multimail`
+* The usual `config/` etc are available too
+
+If that ACL check results in an 'allow' then the multimail plugin will run
+the `git_multimail.py` identified in the Git config from above.
+
+If admins do not wish to grant the capability to all repositories, they might
+consider a rule (before the `include main` in `core.lace`) along the lines of:
+
+    deny "Repositories may not authorise multimail" [operation is multimail]
+
+More complex rule examples may be found on the Gitano wiki.
+
+It's also worth noting that if you are running your instance primarily from the
+gitano-admin user (which is bad and wrong, but some people do do it) then you
+will need to add any denial rules very early since otherwise the allow
+"Administrators can do anything" will kick in and could cause unexpected mails
+to be sent.
+
+### Config
+
+In order to permit a further level of control and flexibility for the multimail
+plugin, configuration is read from four places and combined in order to create
+the configuration which will be passed to `git_multimail.py`.
+
+Firstly there are some defaults in the multimail plugin.  These are there to
+mostly prepare `git_multimail.py` for the fact that it is running under Gitano.
+
+Secondly, the `project.conf` of `gitano-admin` is consulted and anything in
+a `defaults.multimail.` prefix is copied into the configuration, overriding any
+defaults from the plugin itself.
+
+Thirdly, the `project.conf` of the repository in question is consulted, and
+anything in the `multimail.` prefix is copied into the configuration,
+overriding the previous two.
+
+Finally, the `project.conf` of `gitano-admin` is consulted a second time, and
+anything in a `override.multimail.` prefix is copied into the configuration,
+permitting the gitano site administrator to override anything they choose.
+
+This combined configuration is then passed in as additional configuration items
+when `git_multimail.py` is invoked.  In order to protect against wrongdoings
+and potential attack vectors, the names of the configuration items (and note
+the case, since that's important) which will be honoured by the config are:
+
+* `mailingList`: the default location for all emails unless overridden
+* `refchangeList`: the location to which reference change summaries are sent
+* `announceList`: the location for tag notification to be sent
+* `commitList`: the location where actual commit diffs are sent
+
+* `from`: the address from which the mails will be sent.  This takes content
+  of the form `Real Name <email@address>` and defaults to the real name and
+  email address of the entity pushing to the Gitano server.
+
+* `announceShortLog`: if set to `true` this means announce mails include a
+  short log of changes
+* `commitBrowseURL`: The url format string which will be passed for configuring
+  the email bodies to include a URL to the commit.  This is of the form
+  `https://some.server/somewhere/%(id)s` If the string contains the sequence
+  `%(repo)s` then the repository path will be substituted, allowing for site
+  defaults if there is a site cgit.
+* `refchangeShowGraph`: if set to `true`, show the git graph in the ref change
+  summary mail
+* `refchangeShowLog`: if set to `true`, show a patch log in the ref change
+  summary mail
+* `administrator`: if set, this will go into the footer as the administrator
+  of the site.
+* `emailPrefix`: if set, is a summary prefix.  Using `%(repo_shortname)s` will
+  use a shortened repository name automatically
+* `refFilterInclusionRegex`, `refFilterExclusionRegex`, `refFilterDoSendRegex`,
+  `refFilterDontSendRegex`: These configure the refs which `git_multimail.py`
+  will be sensitive to.
+
+* `verbose`: if set to `true` will cause `git_multimail.py` to be somewhat
+  verbose and say what it's up to.
+* `stdout`: if set to `true`, will send the content to the output (returned to
+  the person pushing) instead of emailing it, so that it can be checked prior
+  to enabling the feature properly
+
+In general, see `git_multimail.py`'s documentation for further information on
+the above options.
+
+The multimail configuration is structured as above to allow maximum flexibility
+combined with the ability to control almost all aspects of the multimail
+behaviour with the 'config' command (which can be ACL filtered and delegated).
+
+Regardless of any attempts to set it in config, the `repoName` configuration
+value will be set by the plugin last and thus are not overridable.
+
+Repo owner responsibilities
+---------------------------
+
+If the gitano-admin has delegated permission to switch multimail on and off,
+then the repo owner must set a Lace rule to allow it.
+
+In addition, any configuration for multimail which is necessary for the repo
+should be set in the configuration for it.
+
+If nowhere sets any of the address options, then the multimail plugin will not
+invoke `git_multimail.py` at all.
+
+Hooks
+-----
+
+Just before the multimail plugin applies the above whitelist to the
+configuration data, it will run a hook called 'multimail' whose API is:
+
+    local repo, updates, confbits = ...
+    -- make changes to confbits which is a key/value table of configs
+
+If the hook fails then the plugin will abort.  If the hook alters the
+`confbits` table then the changes will be reflected in the invocation of
+`git_multimail.py` and if the plugin alters the updates table, then those
+changes will be reflected also.  As such, the hook can choose to erase some
+ref changes from the invocation if they so choose.