sitescripts/hg/README.md - Issue 29339623: Issue 3681 - Add suport for "Fixes XXXX - ..." commit messages

Side by Side Diff: sitescripts/hg/README.md

Issue 29339623: Issue 3681 - Add suport for "Fixes XXXX - ..." commit messages (Closed)

Patch Set: Split into two hooks to handle the master bookmark, move documentation to README, add tests Created April 24, 2016, 9:33 p.m.

Left:
Right:

Use n/p to move between diff chunks; N/P to move between comments.

Jump to:

View unified diff | Download patch

OLD	NEW
(Empty)
	1 # Mercurial hooks
	kzar 2016/04/29 14:05:43 Please could you add a brief introduction section 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. Show quoted text On 2016/04/29 14:05:43, kzar wrote: > 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? 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 Show quoted text On 2016/05/02 16:54:03, Vasily Kuznetsov wrote: > On 2016/04/29 14:05:43, kzar wrote: > > 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? > > 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. 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.
	2

	3 There are two hooks contained in `sitescripts/hg/bin/update_issues.py`:

	4 `changegroup_hook` and `pushkey_hook`. The hooks will recognise issue

	5 references in commit messages and update referenced issues in Adblock Plus

	6 issue tracker.

	7

	8 The format of the commit messages is "ISSUE-REFERENCE - MESSAGE"

	9 where ISSUE-REFERENCE is one of "Noissue", "Issue NUMBER" or "Fixes NUMBER".

	10 Several "Issue" and "Fixes" references separated by commas can be present

	11 in the same commit message (for example: "Issue 1, Fixes 2 - Two issues").

	12 Such commit will affect all the referenced issues.

	13

	14 * `changegroup_hook` will post a comment with the link to the commit into the

	15 issue if the issue is referenced from the commit message.

	16 * `pushkey_hook` will close the issues and assign milestones to them (based

	17 on their module) when `master` bookmark passes over the commits that fix

	18 them. It will not assign a milestone if the issue already has one.

	19

	20 ## Configuring the repository

	21
	kzar 2016/04/29 14:05:42 Nit: Looks like a typo around "in"? Nit: Looks like a typo around "in"? Vasily Kuznetsov 2016/05/02 16:54:03 Done. Show quoted text On 2016/04/29 14:05:42, kzar wrote: > Nit: Looks like a typo around "in"? Done.
	22 `changegroup_hook` in should be installed as `changegroup` or

	23 `pretxnchangegroup` hook. `pushkey_hook` should be installed as

	24 `pushkey` or `prepushkey` hook. For example (in `.hg/hgrc`):

	25

	26 [hooks]

	27 pretxnchangegroup = python:.../update_issues.py:changegroup_hook

	28 pushkey = python:.../update_issues.py:pushkey_hook

	29

	30 ## Configuring the hooks

	31

	32 The hooks are configured via `sitescripts.ini` in `hg` and

	33 `hg_module_milestones` sections. For example:

	34

	35 [hg]

	36 trac_xmlrpc_url=https://abpbot:abpbot@issues.adblockplus.org/login/xmlrpc

	37 issue_url_template=https://issues.adblockplus.org/ticket/{id}

	38

	39 [hg_module_milestones]

	40 platform=Adblock-Plus(-[\d\.]+)?-for-Chrome-Opera-Safari(-next)?

	41 Adblock-Plus-for-Firefox=Adblock-Plus(-[\d\.]+)?-for-Firefox(-next)?

	42

	43 `hg.track_xmlrpc_url` key from is used to determine the address of XMLRPC

	44 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 Nit: Slightly too long line here and below Vasily Kuznetsov 2016/05/02 16:54:03 Done. Show quoted text On 2016/04/29 14:05:43, kzar wrote: > Nit: Slightly too long line here and below Done.
	45 the referenced issues that are displayed in the log.

	46

	47 The keys of the `hg_module_milestones` section are module names and the values a re

	48 corresponding milestone regular expressions. The first open milestone that

	49 matches the regular expression of issue's module will be assigned to the issue

	50 when the `master` bookmark passes a commit that fixes it.

	51

	52 ## Master bookmark

	53

	54 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 Nit: Maybe this sentence should end in a question mark? Vasily Kuznetsov 2016/05/02 16:54:02 Done. Show quoted text On 2016/04/29 14:05:43, kzar wrote: > Nit: Maybe this sentence should end in a question mark? Done.
	55 The idea is that if the `master` bookmark _passed_ a commit we will have

	56 those changes in our working copy when we do `hg checkout master`.

	57

	58 Let's first look at a simple case, linear commit history like this:

	59

	60 one <- two <- three

	61

	62 Here `one` is a parent commit of `two` and `two` is a parent of `three`. If

	63 the `master` bookmark was on `one` and then moved to `three`, we say that it

	64 passed `two` and `three`. This would happen naturally if we clone the

	65 repository that contains `one` with the `master` bookmark pointing to it,

	66 check out `master`, author two commits and then push them.

	67

	68 A somewhat similar thing happens when we have branches:

	69

	70 one <---- two <---- three

	71 \ /

	72 \-- dos <--/

	73

	74 Here `one` is a parent commit of `two` and `dos` and they are both parents

	75 of `three`. If the `master` bookmark was on `two` and now is on `three`,

	76 we say that it passed `three` and `dos`. What happened here is that by `three`

	77 we've merged a branch containing `dos` into the master branch that was going

	78 through `one` and `two`.

OLD	NEW

« no previous file with comments | « .sitescripts.example ('k') | sitescripts/hg/bin/update_issues.py » ('j') | sitescripts/hg/bin/update_issues.py » ('J')