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.

Posting a Patch

First, create a diff file using git diff. (Do not use git format-patch.) Log in to Phab and enter Differential. Click the +Create Diff button in the upper-right corner of the screen. Paste the text of the diff or upload the file using the file dialog. Select the project at the bottom, if you start typing it will perform a search among active projects.

For a reviewer, the default is to select the project itself. That means all users who are members of the project will be notified, and any user can approve the patch. In some cases, you will want to request a review from particular people instead.

Note

You must specify at least one reviewer for your diff. If you upload a revision with no reviewers, nobody will get notified.

Using Arcanist

What is Arc?

Arcanist is Phabricator's fully featured command line tool to interface with your local Git repository. It can be used to submit your patches for review. 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 fill in is the reviewer. As mentioned above, the default is to choose the whole project as the reviewer. This can be done in the text by by writing one of the project hashtags in the reviewer field. For example, the default reviewer for Krita is #krita and the default hashtag for KDE PIM is #kde_pim. Additionally, when you create your diff, you can associate it with an existing Maniphest 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 for your new feature.

$ git checkout -b <branchname> origin/master

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

$ 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. Remember that you must enter a reviewer, either by entering a project hashtag or an individual user.

Step 2: Updating your diff.

After you upload the code the reviewer will take a look and give you some comments. If you get a thumbs up, you can skip this step. But often you will get a review like "looks good, we can take it if you fix problems x, y, z." After you make your changes, you can add an extra commit to the git branch.

$ git add -u
$ git commit
$ arc diff

Step 3: Landing your diff.

The following needs you to to have a full KDE Developer Account. If this is one of your first patches to KDE projects, so you do not have one yet, you will need your reviewers or someone else to land the diff.

After the patch is in an acceptable state, the reply to your new message will be: "Ship it!"

$ git checkout <branchname>
$ arc land

This will squash all of the commits in your feature branch together. Phabricator aims for a tight correspondence of one commit = one change = one diff. If you don't want to squash your commits, using Arc for the last step is unnecessary, as Phab will monitor the repo and mark the diff as closed when it sees the commit. You can push using git push instead.

If you are new to Arc, you may want to double-check the commit message before actually pushing to make sure the commit looks as intended. You can do so with arc land --hold, which will squash your feature-branch in a single commit on master, without pushing it. arc land also assumes the upstream branch is called "origin/master." Usually that is the case, but for more complicated workflows some additional configuration is required.

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)."

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