Accept Process

An experimental process for reviewing contributions to Mercurial

1. Overview

Historically, mpm has been the only developer with push access to the canonical Mercurial repo and reviewed every changeset. This experimental process will allow reviewers to bypass mpm by recording multiple approvals. Every change accepted through this process must have at least two approvals distinct from its author.

The first approval is implicit in the push to the hg-committed repo, which can only be done by developers with push access. A pushlog records the author and pusher of each change.

The second approval is done by recording an entry in a ~/.accepted file. Similarly, this can be done only by users with push access (and thus a shell account on the server).

Lastly, a "land" cronjob consults the set of approvals and pulls all the commits that satisfy the invariants. In addition to the two reviewer rule, a commit can only "land" if its parent is already public or is itself landable. It also keeps a log of the reviewers for each commit.

2. Setting up the accept tool

The scripts for the accept process currently live in ~mpm/accept. This currently just adds a full node id to your ~/.accepted file. Eventually, it will also constrain the file to a reasonable length.

To smoothly integrate with a normal hg workflow, a shell alias is recommended:

accept = !ssh mercurial ~mpm/accept/accept $(hg log -r $1 -T '{node}')

Then you can accept the current change thusly:

$ hg accept .

Remember, the usual standards for review apply! Speed this up with an ssh control master

3. The pushlog and the "accepted" script

To see who pushed changeset, you can consult the pushlog. It is currently stored in two ways:

• a permanent history of date, node, and pusher (/srv/hgweb/repo/hg-committed/.hg/push.log)
• a list of draft changes with node, author, and pusher (/srv/hgweb/repo/hg-committed/.hg/accept.log)

This latter is pretty useful. You might want an alias to look at it:

[alias]
pushlog = !ssh mercurial cat /srv/hgweb/repo/hg-committed/.hg/accept.log

Secondly, there's a script ~mpm/accept/accepted that will consult the above log together with every reviewer's .accepted file and generate a list of commits with two or more accepts. This is used as input to the "land" stage and can also be used to figure out which commits still need review.

4. Setting up the revset helper

An experimental extension to support "external revsets" can be found at ~mpm/accept/extrevset.py. It can let you wire a revset predicate to any shell command that returns a list of revisions. This will let you consult the server for a list of changes that still need review right from your favorite "hg log" alias.

[extensions]
extrevset=path/to/extrevset.py

[extrevset]
accepted = shell:ssh mercurial ~mpm/accept/accepted
canreview = shell:ssh mercurial ~mpm/accept/accepted | grep -v myusername

[alias]
review=log -G -r "draft() and canreview()"

5. Setting up the template helper

Another extension called exttemplate.py allows shell-powered template keywords:

[extensions]
exttemplate = /path/to/exttemplate.py

[exttemplate]
reviewers = shell:ssh mercurial ~mpm/accept/reviewed

Add this to your favorite log template to get reviewer information:

$ hg log -r "draft()" -T "{rev} {reviewers}\n"

6. Future work

This sort of works today, but there's a lot more to do:

• support accepting multiple commits
• non-polled landing
• hgweb support for showing reviewers
• http-based queries to get to-review set
• migration of the primary repo to mercurial-scm.org
• more sanity checks
• a way to place temporary holds on commits
• external source of truth for list of reviewers
• more knowledge about email aliases
• integration of scripts into the hginfra repository