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 is a feature-branch workflow. I keep a master branch, and each patch becomes a different branch. With the correct upstream branch set, I use arc diff with no arguments to create a new diff. After receiving feedback and making changes, I alter the Git commit with git commit --amend --no-edit (Actually I perform a commit extend in Magit.) A second arc diff while on the edited branch and Arc will ask me for a comment message and update. Finally I merge my feature branch and use Git to push; Phab will automatically close the diff when it detects the repository has been updated. Alternatively, arc land can be configured to do the merge-and-push automatically.

Online 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.