Phabricator

We've set up an instance of Phabricator that we're going to experiment with for code reviews. At this time, we're not planning on using any of the other features of Phabricator, and the use of Phabricator for reviews is very much an experiment - we intend to see how this is going in a little while (probably around the start of the 4.4 cycle). If you're more comfortable submitting and reviewing patches as plain email, that's fine - use of Phabricator is optional.

1. Registering for an account

To use Phabricator, you can log in with an existing Google, Facebook, or Bitbucket account, or sign up for a standalone Phabricator account at https://phab.mercurial-scm.org/auth/register/.

2. Setting up hg

We've got a custom extension that should make working with Phabricator a little more pleasant. It requires the prerelease of hg 4.3 or later. You can enable it for just your hg repo by editing .hg/hgrc and adding the following:

[phases]
# Use draft commits
publish = False

[extensions]
# 4.8 and newer
phabricator =

# older than 4.8
phabricator = path/to/hg/contrib/phabricator.py

[experimental]
# obsstore needs to be used for tracking which commit belongs to which Differential Revision and their versions.  This section isn't necessary if the evolve extension is enabled.

# 4.4 and later
evolution.createmarkers=true
evolution.allowunstable=true

# older than 4.4 (and may hide evolve commands if the evolve extension is enabled.  See the 'experimental.evolutioncommands' config.)
evolution = createmarkers, allowunstable

[phabricator]
url=https://phab.mercurial-scm.org/
callsign=HG

# replaced by [phabricator.auth] in 4.6
token=cli-SOMENOISEHERE

# 4.6 only
[phabricator.auth]
hg.url = https://phab.mercurial-scm.org/
hg.token = cli-SOMENOISEHERE

# 4.7 and later
[auth]
hg.schemes = https
hg.prefix = phab.mercurial-scm.org
hg.phabtoken = cli-SOMENOISEHERE

You can get your API token for Phabricator here.

3. Submitting a patch

Our expectation right now is that you'll run tests (as appropriate) and then use hg phabsend to post patches to Phabricator.

To send a stack, use hg phabsend 'BEGIN_REV::END_REV', or choose whatever revsets suitable for you like hg phabsend '. % @'. If you send patches individually and want to make them a stack later, you can change the dependency by clicking "Edit Related Revisions" on the webpage.

If you are sending a simple stack (i.e. no other revisions after END_REV), it's recommended to use hg phabsend --amend 'BEGIN_REV::', which will change the commit message to include the Differential Revision URL so they get "associated". Otherwise, hg phabsend writes local tags to track what was sent to what Differential Revision. When running hg phabsend REVSET again, it updates commit message and actual patch contents if commits are associated with Differential Revisions.

4. Accepting a patch

You'll want to use hg phabread, potentially with the --stack flag, for this. Make sure to check that the authorship information is correctly preserved: we've seen some weirdness when people use arc diff instead of hg phabsend.

5. Customization

Jun has a user script which may make reviewer interface cleaner and easier to use (ex. "[", "]" to navigate among a stack).

To use the user script, a browser extension enabling user script feature is needed. It could be Tampermonkey for Chrome, or Greasemonkey for Firefox.

6. Phabricator is terrible, I hate it! || Phabricator is awesome, stop using emails!

So is the alternative, just in different ways! But do keep feedback in mind (maybe take notes). We'll probably send around a form to fill in once enough traffic has been run through Phabricator to see how people feel about it.

7. Augie's Notes

So far, phabricator seems to be better for contributors, but mostly negative for veteran reviewers. It's my sense that we need:

• A dashboard with per-user "unread" state (or "needs attention" state) for each patch series (maybe per-patch? I'm not sure because my current workflow is series-based.
• Clean up the emails a bit so they don't bury the lede (for example "From: durin42" then first line is "durin42 made a comment")

Nice to haves:

• Improved threading so that stacks use an in-reply-to header and group a whole stack as one thread (maybe very hard with phabricator's data model)

I'd welcome feedback (publicly or privately) on Phabricator. I know it's been rough, but I've seen it be enough easier for some contributors that I don't want to give up without trying a little more to make it work. I'll probably put together some kind of survey early next week.

8. Using arcanist

Our extension should interoperate with arcanist-created reviews correctly now. If you want to use arcanist, put this in .arcconfig in your repo:

{
  "conduit_uri": "https://phab.mercurial-scm.org/api",
  "repository.callsign": "HG",
  "arc.land.onto.default": "@",
  "base" : "hg:.^",
}

You may also want to set   "history.immutable" : false in there, but AugieFackler doesn't remember what that does.

---

CategoryDeveloper