Accept Process

An experimental process for reviewing contributions to Mercurial

1. Overview

Historically, mpm was the only developer with push access to the canonical Mercurial repo and reviewed every changeset. This process allows reviewers accept changes 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. This can be done by developers with accept access, which is a subset of those with push access.

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

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

[alias]
accept = !ssh mercurial-scm.org /opt/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-scm.org cat /srv/hgweb/repo/hg-committed/.hg/accept.log

4. Setting up the revset helper

An experimental extdata() revset 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.

[extdata]
accepted = shell:ssh mercurial-scm.org /opt/accept/accepted
canreview = shell:ssh mercurial-scm.org /opt/accept/reviewed | grep -v myusername

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

5. Setting up the template helper

An experimental extdata() template function allows shell-powered template keywords:

[extdata]
reviewers = shell:ssh mercurial-scm.org /opt/accept/reviewed

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

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

6. Rebasing and diffhashes

The accept process doesn't use obsolete markers because they're a little too generous. We don't want subsequent non-trivial edits to automatically get the sign-off of earlier accepters.

Instead, we calculate a "diffhash" of each diff that excludes line numbers, dates, and descriptions. It thus survives most of the trivial rebases and typo fixes in descriptions that we don't care about. This is used to carry forward accept markers from earlier commits with the same diffhash.

Keep in mind that a push of a rebased changeset counts as the second acceptance so be careful not to push anything you don't mean to.

Typo fixes in code comments DO invalidate the hash, so please get those cleaned up on the first pass.

7. 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
• more sanity checks
• a way to place temporary holds on commits
• more knowledge about email aliases

8. hgrc configuration

AugieFackler has published his configuration for accept process work, in case others find it useful.

CategoryDeveloper