Phabricator User Guide

Phabricator is a task management system which KDE is transitioning toward. It is written in php (hence the ph) and structured as a collection of applications, most of which take the form of web modules. These modules can be seen on the left hand side of the KDE Phabricator, with names like Differential, Maniphest, and Phriction.

Phabricator is under very active development, but is already an excellent tool. This page is intended to serve as a general-purpose introduction to the most important aspects: submitting and reviewing patches. It should not take long before you are happily using Phabricator. If you are not happy, you can submit bug reports to to Phabricator's own Phabricator to request changes. Note this can address only Phabricator-related unhappiness, but not deeper life issues.

The modular structure allows projects to flexibly create their own workflows. Project maintainers should keep developers and contributors up to date with more specific guidelines on their pages in the KDE Community Wiki or Phriction.

Basic Tasks

Logging in

The first challenge posed by Phab is logging in. You will use your KDE Identity account for this. If you don't have one, you can sign up for one here . At the Phabricator login screen, enter that username and password in the "Login or Register with LDAP," which is the lower form. Hopefully this will be clarified and simplified in the future.

Getting help

The official documentation is in the Phabricator book and on their website -- note the official website is full of puns -- but since everything is under rapid development most of the documentation is incomplete. A good way to find the information you're looking for is to search Phab upstream. The search is in the upper right hand corner. In the future the official documentation may be hosted on the KDE site.

Phab Apps

Luckily the use of most of the web applications is described in a small tag line. Differential and Maniphest, the code review and task management applications, are where you should expect to spend most of your time. Calligra intends to collect information for developers in Phriction. You can also create your own to-do list in Dashboard. In addition to the pages which are listed there are more applications available. Some others not listed on the main page by default are Pholio, for discussing mockups, Slowvote, for conducting user polls, and Paste, for sharing text snippets.

Using Arcanist

What is Arc?

Arcanist is Phabricator's excellent command line tool to interface with Git and other VCS systems. It tries hard to do the right thing and make sure it is doing the right thing. Like the rest of Phabricator it is written in PHP. After you have installed Arc, you can learn more using man arc or arc --help. Another command useful for getting a feel for Phabricator's style is arc anoid.

Installing on Linux

Although Arc is provided in the official Ubuntu repository and presumably others, at the time of this writing, the development is too fast paced for this version to be up-to-date. A better idea is to install from upstream; this requires downloading their php library libphutil as well as Arcanist. A script to do this automatically in Ubuntu is here. You will need the php command line and CURL packages: in Ubuntu, php5-cli and php5-curl.

Installing on Windows

There is information on Arcanist. Installing Arcanist on Windows is not much harder than on Linux, but getting php is a little more involved, since there is no package manager. You will need to configure your Php installation script to use Curl.

Connecting to KDE

Your project repo should contain the file .arcconfig in the root directory. If not, here is a simple template. The only additional information Arc needs is your login identifier. This is as simple as going to the link https://phabricator.kde.org/conduit/login/ and installing your API token with arc install-certificate.

Posting Patches

The basic command to interface with Differential, the patch review system, is arc diff. By default, this command will try to take your current git patch and create a new Differential to submit for upstream review. It will reformat Git commit message, asking you to provide reviewers and providing the URL to the newly created diff. In the same way the KDE bugtracker will read from the commit template and automatically close bugs, Phabricator reads commit messages and will update Maniphest and Diff automatically. Here is more information about the special messages it looks for.

Workflow

The basic workflow I have found successful with Arc is a feature-branch workflow. I keep a master branch synchronized with the upstream, and make all of my changes on separate branches.

Step 1: Creating a new diff.

Before editing anything, create a new branch with the proper upstream.

$ git checkout -b new-feature origin/master

Make or cherry-pick changes into this feature branch. When you're ready to have your changes reviewed:

$ git add -u
$ git commit
$ arc diff

When you run arc diff, you will go through a series of dialogues. You will be asked to rewrite your Git commit message to fit the standard Differential format. In particular you will mention the reviewers, and the commit message will contain the URL to view it in Differential, e.g. https://phabricator.kde.org/D152

Step 2: Updating your diff.

After you upload the code the maintainer will take a look and give you some comments. "Looks good, it's ready to go if you fix problems x, y, z." After you made your changes, instead of creating a new Git commit, you can extend the old one. The goal of here is a tight correspondence: one commit = one change = one diff. Magit's "extend commit" is perfect, but in the unfortunate situation you do not have access to Magit, it can be done manually like this:

$ git add -u
$ git commit --amend --no-edit
$ arc diff

Arc will know what to do here. It reads the message of the original commit, but sees that the content has changed. It will therefore update the patch while prompting you to comment about what is different. The comment will not go in the commit message; if you want to change the commit message remove the --no-edit.

Step 3: Landing your diff.

With luck, the reply to your new message is: "Ship it!"

$ git push
$ git checkout master
$ git merge new-feature

Using Arc for the last step is unnecessary, as Phab will monitor the repo and mark the diff as submitted when it sees the commit. Alternatively, arc land can be configured to do this merge-and-push automatically, but you will need to be careful about setting your preferences if upstream is not called "origin/master."

Review: Differential and Maniphest

Information

These are more self-explanatory than Arc and mostly follow the layout of a public forum. Before sharing links to internal Phabricator pages and diffs, be sure they are configured to be "Visible to Public (No Login Required)." I'm not sure if there's a way to set this automatically.