Guide: Code Contributions

Instead of GitHub Pull Requests, we use Phabricator Differential. Here’s how to get started with one.

First Time Setup

The first time you work with our repositories code, you’ll want to set up your development environment. You’ll also need to read Guide: Building Code.

Getting Ready

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 devel. 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 “devel”, “fresh”, or “stable”).

Making Changes

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.

Landing Changes

Once your Differential Revision has been approved, you can land it, meaning you push the changes to the devel branch. In the repository, run…

$ arc land yourbranchname --onto devel

…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 devel branch, and it is up-to-date.

$ git checkout devel
$ git pull origin devel

Then patch the Differential Revision with…

$ arc patch D###

…where D### is the Differential Revision ID (such as D123).

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 via…

$ git branch -m arcpatch_D### newbranchname