- Set yourself up
- Workflow for review requesters
- Workflow for reviewers
- Using Diffusion
- Future plans
Phabricator is an online utility that provides a presubmit code review workflow (among many other things). Patches are uploaded to the service via a command-line tool, reviewed by appointed developers and committed once the changes have been approved.
This page describes how to use Phabricator in the context of the FreeBSD source tree and the ports tree by using the service instance at https://reviews.freebsd.org/.
Set yourself up
Before being able to send code reviews out, you need to create an account on the online service and install the command-line client tools on your machine. This section details this process.
Create a Phabricator account
By default, the review service is open to developers that have a @freebsd.org address. If you are one, visit https://reviews.freebsd.org/auth/register/ to create your account. Others should contact email@example.com to request an account.
Please use your FreeBSD username as your account name and your FreeBSD email address so that the Phabricator admins can track who you are.
Arcanist is a command-line tool to interact with Phabricator. Simply install it via binary packages by typing:
# pkg install php5-arcanist
... or from ports if you wish to build it yourself:
# cd /usr/ports/devel/arcanist ; make install
Set up Arcanist
Set up ~/.arcrc with the certificates required to access the online service. This process requires manually copy/pasting a cookie provided by the online service. Do this by typing the command below and following the online instructions:
$ arc install-certificates https://reviews.freebsd.org
Workflow for review requesters
Once you have finished preparing a change locally, you are ready to send it out for review.
Please make sure that your patch does one thing (and one thing only) so that the review process goes smoothly. Small and self-contained patches are much easier to review!
Phabricator has separate classes of participants in a review: Reviewers and Subscribers. Individuals and project groups may be Reviewers, and at least one reviewer must accept the review. Subscribers are notified of the review and any changes, but are not required to accept the review. Subscribers may be individuals, project groups, and mailing lists.
Upload the patch from the command line
From the top of the svn tree, run the following command to create a new patch affecting the given paths:
$ arc diff --create [<path>] ...
This command will open your favorite editor with the following template to fill in:
<<Replace this line with your Revision Title>> Summary: Test Plan: Reviewers: Subscribers: # NEW DIFFERENTIAL REVISION # Describe the changes in this new revision. # # arc could not identify any existing revision in your working copy. # If you intended to update an existing revision, use: # # $ arc diff --update <revision>
Use these guidelines:
The Revision Title is mandatory. This should be a one-liner description of your change.
The Summary is optional. However, you should fill it in with the verbatim contents of the commit message you will later use when submitting the change.
The Test Plan is optional. Describe here how you have tested the patch and/or how the reviewer can test it. If you cannot come up with anything, think twice...
The Reviewers is optional. However, you should indicate the list of FreeBSD committers that you expect to review the patch. If such committers have accounts on Phabricator, they will automatically be notified of your submission. You can also directly add reviewers using --reviewers <nicks> when using arc diff command. e.g. --reviewers #portmgr. reviewers can be either <nick> or #<project>
After saving and exiting your editor, the patch will be uploaded to the Phabricator service and Arcanist will print a tracking link for your review:
Uploading the patch through the web interface
Patches can be created without having arc installed by uploading a patch through the web interface. Patches can be created by diff, svn, git, or other tools.
To make reviews easier, always include as much context as possible with your diff! Phabricator will automatically reduce the context in the default display and when sending emails, but it allows the full context to be displayed on demand in the web interface.
To get a full diff, use one of the following commands.
git diff -U999999 other-branch svn diff --diff-cmd=diff -x -U999999
To upload a new patch:
Click Create Diff in the upper right hand corner.
- Paste the text diff or upload the patch file.
Leave the drop down on Create a new Revision... and click Continue.
- Enter a descriptive title and summary
- Add reviewers and mailing lists that you want to be included in the review. Mailing lists are added as subscribers:
- Click Save.
To submit an updated patch:
Click Create Diff.
- Paste or upload the updated diff.
Select the review you want to update from the Attach To dropdown and click Continue.
- Click Save.
Address review comments
If the reviewer does not approve your change and asks you to modify stuff in your patch, edit the files in your local client accordingly.
While doing so, fill in replies to any line-specific comments that the reviewer may have left on the site. Don't worry: saving those replies does not cause them to be sent out yet. You must click the Submit button at the very bottom to cause these to be sent out.
After addressing all comments, reupload the patch. path should included all paths that are part of the review, even if their contents haven't changed as part of this update.
arc diff --update DXXX [<path>]
Note that this will trigger a notification to the reviewers mentioning that the patch has been updated.
Get approvals and submit
Once the reviewers are happy with your change, they will approve your patch (which will be denoted by a green tick on the web site). At this point, you are free to submit the change to svn. Just use svn commit as usual. NOTE: Do not use arc commit because it will not allow you to edit the commit message, and will use a non-standard (for FreeBSD) format.
If you use git you can also now do "arc amend".
Close the review
It is important that you close the review once you are done with it so that it does not clutter your dashboard nor your reviewers'. Do this by scrolling down to the bottom of the review page, select the Close option from the Action dropdown menu just above the Comment field, and click Submit. The Close option will not be visible unless the review is in the Approved state.
You can close a revision (in any state) from the command line with the following:
arc close-revision DXXX
Workflow for reviewers
This workflow applies to people reviewing patches sent to them via Phabricator.
Open the patch
Click on the link that appears in the notification email you received to open Phabricator.
Review the change and send comments
Review the commit message provided along the patch and the diff for all affected files.
If you want to leave line-specific comments, do so by clicking on the line number. This will open a little popup under the line, allowing you to type whichever comment you may like.
If you have change-wide comments, scroll down to the bottom of the page and type them in the provided box. Note that line-specific comments are vastly preferred over change-wide ones!
Once you are done with your review, don't forget to click on the Submit button at the end.
Optional: Apply the patch locally
If you wish to test the patch on your machine, you can use Arcanist to download and apply it. Simply do:
$ env CURLOPT_SSL_VERIFYPEER=0 arc patch D32
Diffusion is the repository browser of Phabricator. It can be used to comment on already existing code in the repository. That way, you can start a review for files in the source tree. The use is similar to reviewing a proposed patch. For example, you want to make comments on a source file.
1. Go to Diffusion which you can find on the left side of your Phabricator main page.
2. Click on the repository where the file is located (doc, src, ports).
3. Use the list of recent commits to locate the commit and click on it (for example r12345). You can also use "Browse" to navigate to the file.
4. Once you are in the phabricator view where you see the graphical diffs, make your comments on the source lines, same as when doing reviews.
5. On the action combo box at the bottom, choose "Raise concern".
- Integrate FreeBSD templates located into subversion ports (devel/subversion/files/extra-patch-fbsd-template)
- FreeBSD templates in arcanist diff (src/differential/ArcanistDiffWorkflow.php)
- Review reference in commit log.
Some commits have used CR:<tab><tab>DXXX as done with PR:<tab><tab>category/id (see r355492)
Phabricator's canonical notation is "Differential Revision: <URL>" which causes commits to update the review automatically.
- URL is not yet permanent, so resolution of this item is open pending Phabricator becoming permanent.
<add your ideas>