Guide: Code Contributions¶
Instead of GitHub Pull Requests, we use Phabricator Differential. Here’s how to get started with one.
First Time Setup¶
Before you start making changes, you should reference the Programming Workflow, so you know what’s expected. For each batch of changes, you should plan them out on Phabricator Maniphest before starting.
Before you make any changes, you should create a new branch on your local
copy of the repository. You should never work on
master. To create
a new branch, run...
$ git checkout -b newbranchname
...where newbranchname is the name of the branch you’re creating. You can call it absolutely anything (except “master” or “stable”).
Now you can begin working. Every day you finish work, you should diff your changes, meaning you upload them to a Differential Revision. To create a Revision, or update the one you already have open for the repository, run...
$ git add . $ git commit $ arc diff
The first time you run
arc diff, it will bring up a form for you to fill
out to create a new Revision. Give it a brief, descriptive title. Describe
your overall plans in the description.
If you’re ready for code review and feedback, add a reviewer. If you don’t know who to add, you can use the Reviewer Finder (see Reviewer Finder) to find someone. You should especially favor tagging someone in the same code territory you’re working in.
If you’re NOT ready for review, don’t worry. You can always add a reviewer later.
You should be aware of the Revision Checklist, which your Revision must pass before it can be accepted and landed.
Once your Differential Revision has been approved, you can land it, meaning you
push the changes to the
master branch. In the repository, run...
$ arc land yourbranchname
...where yourbranchname is the name of the branch you’ve been working in.
Be sure to keep your Maniphest tasks up-to-date, marking them as complete or updating them as appropriate.
Finally, sit back and relax, knowing you’ve made a valuable contribution to MousePaw Media! (When you’re done relaxing, feel free to start a new set of changes.)
Pulling Down A Revision¶
If you want to pull down someone else’s Differential Revision to your local repository for testing it out, or if you want to recover your lost work from your Differential Revision, Arcanist can do that!
First, make sure you’re on the master branch, and it is up-to-date.
$ git checkout master $ git pull origin master
Then patch the Differential Revision with...
$ arc patch D###
D### is the Differential Revision ID (such as
This will create a new branch called
arcpatch_D###. You may want to take
note of the original branch name mentioned on the Differential Revision page,
and rename the
arcpatch_D### branch to the correct name. You can do this
$ git branch -m arcpatch_D### newbranchname