Infrastructure/Phabricator

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 may only address Phabricator-related unhappiness.

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 good option is to install directly from upstream. You will need the php command line and CURL packages: in Ubuntu, php5-cli and php5-curl. Then you can download the repositories and add the arc command line tool to your command line. A script to do this automatically in Ubuntu is here.

Installing on Windows

Downloading the Arcanist web scripts on Windows is no different than on Linux, but getting php is a little more involved, since there is no package manager. Phabricator has a more complete installation guide.

• Arc installation guide
• Php installation guide

The most non-obvious step is that you will need to configure your Php installation to use Curl. This requires editing the php.ini configuration file to add the line extension_dir = "ext" and add php_curl to the list of extensions.

After adding php.exe to your path and installing arcanist/libphutil, you can run arc by defining a function in your Powershell profile:

 function arc { php -f "C:\path\to\arcanist.php" -- $args }

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 into something like this:

<first line of original git commit message>

Summary: <rest of original commit message>

Reviewers: 

Differential Revision: <URL to the new diff>

The only thing you will have to provide is a reviewer request. Additionally, when you create your diff, you can automatically associate it with a task by adding a line like

Maniphest Tasks: T50

Phabricator does not require Arcanist for every upstream transaction. 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." If you choose to use Arc, it's a good idea to double-check the commit message before actually pushing. You can do so with arc land --hold, which will squash your feature-branch in a single commit on master, without pushing it.

Review

Discussions on Diff and Maniphest

Diff and Maniphest are used for coordinating changes and pre-reviewing patches. These are more self-explanatory than Arc and mostly follow the layout of a public forum, like Review Board or Github. Before sharing links to Phabricator pages and diffs on the KDE forums or bug tracker, be sure you have configured them to be "Visible to Public (No Login Required)." I'm not sure if there's a way to set this automatically.

Customization

Creating custom dashboard feeds

You can customize your Phabricator homepage by creating a new dashboard. However the selection of what you can post on your dashboard is limited. The defaults will show all tasks from all projects.

To narrow this down, you need to define a custom query to serve as a filter. For example, if you work on Plasma Mobile and want to monitor the to-do list, perhaps you want to show only tasks which are in the Plasma Mobile and are tagged as open. To do that, enter Maniphest, select "advanced search," select the appropriate terms, then click "save custom query." You can give your query a name. Once it is saved, the query will become available as a new filter for creating feeds on your dashboard. (In Differential you seem to need to perform the test search before the "save query" button becomes visible.)