Issue 3681 - Add suport for "Fixes XXXX - ..." commit messages

sitescripts/hg/README.md

Index: sitescripts/hg/README.md
===================================================================
new file mode 100644
--- /dev/null
+++ b/sitescripts/hg/README.md
@@ -0,0 +1,78 @@
+# Mercurial hooks

[kzar, 2016/04/29 14:05:43]

Please could you add a brief introduction section that quickly explains the
rough idea of sitescripts.hg? A sentence or two is fine, just to help someone
who isn't familiar with the code decide if this is the module their looking for
and to give a little context.

Edit: The first two sentences from the module's docstring would work as a good
introduction here. Maybe just copy them?

[Vasily Kuznetsov, 2016/05/02 16:54:03]

If we're adding an introduction about sitescripts.hg, it makes sense to also at
least mention the irchook. Unfortunately there's no documentation for it and not
even a configuration example, so it's a bit hard to see what it's doing. From
the name I guess that it posts commit references to IRC, so I left it at that
for now.

Let me know if you know more, I'd be happy to add it here. It probably should be
a separate issue though.

[kzar, 2016/05/03 06:47:35]

You're right, this looks fine for now and at some point in the future hopefully
we can add more documentation about the IRC integration.

+
+There are two hooks contained in `sitescripts/hg/bin/update_issues.py`:
+`changegroup_hook` and `pushkey_hook`. The hooks will recognise issue
+references in commit messages and update referenced issues in Adblock Plus
+issue tracker.
+
+The format of the commit messages is "ISSUE-REFERENCE - MESSAGE"
+where ISSUE-REFERENCE is one of "Noissue", "Issue NUMBER" or "Fixes NUMBER".
+Several "Issue" and "Fixes" references separated by commas can be present
+in the same commit message (for example: "Issue 1, Fixes 2 - Two issues").
+Such commit will affect all the referenced issues.
+
+* `changegroup_hook` will post a comment with the link to the commit into the
+  issue if the issue is referenced from the commit message.
+* `pushkey_hook` will close the issues and assign milestones to them (based
+  on their module) when `master` bookmark passes over the commits that fix
+  them. It will not assign a milestone if the issue already has one.
+
+## Configuring the repository
+

[kzar, 2016/04/29 14:05:42]

Nit: Looks like a typo around "in"?

[Vasily Kuznetsov, 2016/05/02 16:54:03]

Done.

+`changegroup_hook` in  should be installed as `changegroup` or
+`pretxnchangegroup` hook. `pushkey_hook` should be installed as
+`pushkey` or `prepushkey` hook. For example (in `.hg/hgrc`):
+
+    [hooks]
+    pretxnchangegroup = python:.../update_issues.py:changegroup_hook
+    pushkey = python:.../update_issues.py:pushkey_hook
+
+## Configuring the hooks
+
+The hooks are configured via `sitescripts.ini` in `hg` and
+`hg_module_milestones` sections. For example:
+
+    [hg]
+    trac_xmlrpc_url=https://abpbot:abpbot@issues.adblockplus.org/login/xmlrpc
+    issue_url_template=https://issues.adblockplus.org/ticket/{id}
+
+    [hg_module_milestones]
+    platform=Adblock-Plus(-[\d\.]+)?-for-Chrome-Opera-Safari(-next)?
+    Adblock-Plus-for-Firefox=Adblock-Plus(-[\d\.]+)?-for-Firefox(-next)?
+
+`hg.track_xmlrpc_url` key from is used to determine the address of XMLRPC
+interface of Trac and `hg.issue_url_template` as a template for producing links to

[kzar, 2016/04/29 14:05:43]

Nit: Slightly too long line here and below

[Vasily Kuznetsov, 2016/05/02 16:54:03]

Done.

+the referenced issues that are displayed in the log.
+
+The keys of the `hg_module_milestones` section are module names and the values are
+corresponding milestone regular expressions. The first open milestone that
+matches the regular expression of issue's module will be assigned to the issue
+when the `master` bookmark passes a commit that fixes it.
+
+## Master bookmark
+
+What exactly does it mean when we say _`master` bookmark is passing a commit_.

[kzar, 2016/04/29 14:05:43]

Nit: Maybe this sentence should end in a question mark?

[Vasily Kuznetsov, 2016/05/02 16:54:02]

Done.

+The idea is that if the `master` bookmark _passed_ a commit we will have
+those changes in our working copy when we do `hg checkout master`.
+
+Let's first look at a simple case, linear commit history like this:
+
+    one <- two <- three
+
+Here `one` is a parent commit of `two` and `two` is a parent of `three`. If
+the `master` bookmark was on `one` and then moved to `three`, we say that it
+passed `two` and `three`. This would happen naturally if we clone the
+repository that contains `one` with the `master` bookmark pointing to it,
+check out `master`, author two commits and then push them.
+
+A somewhat similar thing happens when we have branches:
+
+    one <---- two <---- three
+         \            /
+          \-- dos <--/
+
+Here `one` is a parent commit of `two` and `dos` and they are both parents
+of `three`. If the `master` bookmark was on `two` and now is on `three`,
+we say that it passed `three` and `dos`. What happened here is that by `three`
+we've merged a branch containing `dos` into the master branch that was going
+through `one` and `two`.