Infrastructure/Phabricator

Phabricator is KDE's task management and patch review system. 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.

Information

The KDE community does not use the Phabricator bug reporting function. We continue to use bugzilla at https://bugs.kde.org

Basic Tasks

Logging in

Log in to Phabricator with your KDE Identity account. If you don't have one, you can sign up for one here. At the Phabricator home page, click the "Log in" button on the top of the page and enter your KDE Identity username and password:

Getting help

The official documentation is in the Phabricator book and on their website -- note that 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 Phabricator upstream.

Posting a Patch using the website

Log in to Phabricator and click on Code Review in the list on the left. Then, 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. Reviewers are mostly added automatically, but if your patch includes any visual or user interface changes, please add #vdg as a reviewer to make sure the KDE Visual Design Group sees it! Please make sure to add a screenshot, too.

Formatting your patch

In the Summary section, write at least one sentence describing your change and why it is necessary, adding more details if necessary.

Add special keywords

If your patch is intended to fix a Bugzilla ticket, include one of the following on its own line in the Summary section:

BUG: 385942

or

FEATURE: 384936

(Just the Bugzilla ticket number, not the full URL)

Use BUG: If the Bugzilla ticket describes a bug, and FEATURE: if the Bugzilla ticket describes a feature request. Either of these tags will cause that Bugzilla ticket to be automatically closed when the patch is committed.

If you added the BUG: or FEATURE: tag, also add another tag indicating what version receives the fix or new feature:

FIXED-IN: [version]

Replace [version] with an appropriate version string; see Guidelines and HOWTOs/Write a version string to find out how to write one. If you can't figure it out, don't worry about it and just omit the tag; a KDE developer will help you add it during code review.

These keywords will only work if the email address in your .gitconfig file matches the email address used for your https://bugs.kde.org account (See this page for more information).

Include some screenshots

For patches that change something about the user interface, it's customary to include a screenshot of how the interface looks with your patch. Bonus points for including a "Before" image too, so reviewers can easily compare them.

What happens next?

After you've submitted your patch, KDE developers who work with the software in question will review it and provide feedback. This can often take a few days. However, if nobody has responded after a week, it's likely that the review was overlooked (sorry about that!) and it's appropriate to make a comment saying, "Ping!" or something to that effect.

Once the patch is accepted, KDE Developers will land it for you!

Using Arcanist to post patches

After you've posted a few patches, using the web UI to post patches gets tiresome. Arcanist is a tool to simplify and speed up the process of posting, updating, and merging Phabricator patches. Setting it up is easy:

Windows

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 }

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.

Workflow

The sanest and easiest way to use arc is to follow a typical feature branch workflow: keep your master branch synchronized with the upstream repository, and make all changes on separate branches. Each patch needs its own private, temporary branch. Once your patch has been merged, delete the feature branch, and make another new branch for the next patch.

The following commands all need to be executed in your source directory. The hidden file/directory ".arcconfig" and ".git" tell arc what to do so you don't have to.

As when using the web UI, enter any special Bugzilla keywords (such as BUG: 385942) on their own lines in the "Summary" section.

As when using the web UI, there is no need to specifically add anyone under the "Reviewers" or "Subscribers" sections unless your patch includes any visual or user interface changes. In this case, please add #vdg as a reviewer to make sure the KDE Visual Design Group sees it!

Step 2: Update your diff in response to review comments

After arc uploads the patch to Phabricator, the project's reviewers will take a look and give you some comments. If you get a thumbs up immediately, 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, and z." Make the necessary changes, add an extra commit to the git branch, and update the Phabricator revision:

[implement changes based on review comments]
arc diff

Step 3: Land your diff

If you do not have a KDE Developer Account, then someone who does will have to land your patch for you. Otherwise, you can do it yourself once the patch has been accepted and reviewers have given you permission to "ship it!"

First, make sure that the world is sane, and that only your patch will be landed:

[make sure you are on your feature branch]
arc land --preview

The output of that command should show only the commit message for your patch. If you see more than that, stop and ask your reviewers for help.

Landing on master

This is simple:

arc land

Landing on the "Stable branch"

By default, arc will land the patch onto whatever branch was the parent. For example, if you branched from master, arc will land on master; if you branched from Applications/18.12, arc will land on that branch instead, and so on.

If you branched your patch from master but it is a relatively low-risk bugfix, you will often be a asked to land it on the "stable branch" instead of master. The easiest way to do this is to cherry-pick the commit from your feature branch onto the appropriate stable branch and then merge forward.

Warning

If at any time you feel nervous or run into trouble, ask your reviewers for help. This can be tricky, and undoing bad merges is a pain in the neck.

Here is an example of how to do this with a patch branched from master that needs to go into the Applications/18.12 stable branch (replace Applications/18.12 with the appropriate stable branch name when you do this yourself, obviously).

Landing someone else's diff

If you have a contributor account and you are helping someone without one through the process, you will need to land their diff for them once it's been accepted. Here's how:

arc patch <revision ID>
git show HEAD

At this point, you need to verify that the authorship information shown is correct. If it's not, you will need to ask the patch author for their real name and email address. Then you use that information to update the local commit for the patch like so:

# Make sure you're on the branch that corresponds to the patch!
git commit --amend --author="firstname lastname <email address>"

Arcanist Tips & Tricks

Look before you diff

You can check with arc which what Arcanist will do before performing the actual upload with arc diff if you are unsure what will happen. In particular, look for which commits will be included in your Diff.

arc diff: specify a revision manually

Sometimes - if you messed up with your git branches - arc cannot properly determine which revision (D12345) should be updated. In this case you can use arc diff --update D12345. See arc help diff.

Updating the summary of the Differential from the local Git commit message

If you changed the commit message locally and want to update the text in the summary in Differential, call Arc like this:

arc diff --edit --verbatim

Updating the local Git commit message from changes done on Phabricator

If you or someone else updated the title, summary, test plan, reviewers or subscribers of a Diff using the web editor in Phabricator, Arcanist allows to sync those changes back to your local Git commit message:

arc amend

Note that in general Arcanist will do this automatically for you once you arc land.

Advanced Tasks

Once in a while, a reviewer will tell you to do specific things. This section will help you figure out what is meant to be done.

"Please do that in a separate commit"

Should your patch contain an unrelated change, your reviewer will ask you to undo that part and possibly open a new Diff for that. Here is what you can do:

If the change in question is in a separate commit on your local branch:

As above, implement the feature and make a commit. Continue this pattern for any other required dependent features.

When you're ready to turn your dependency chain feature branches into patches, do the following:

git checkout <branch name for feature 1>
arc diff [then go through the process of creating the patch normally]
git checkout <branch name for feature 2>
git commit --amend [then add the special text "Depends on DXXXX", replacing DXXXX with the ID of the first patch
arc diff [then go through the process of creating the patch normally]

...And so on.

After you get comments, you will have to make changes to your patches and re-base dependent patches:

Apply the patch and compile the software

Now check out or enter the source repository for the software that's being patched. The repository is listed on the web UI:
...So this would be a patch for Konsole.

If you've never built it before, check it out and build it once first:

kdesrc-build konsole

Now go to its source directory:

cd ~/kde/src/konsole

...and apply the patch:

arc patch <revision ID>

Answer y to any questions that are posed. Arc will automatically create a branch named arcpatch-<revision ID> for the patch, so it won't damage your checkout at all.

Now it's time to compile and run the software to make sure that the patch does what it says it does and doesn't cause any regressions! Compile the patched source code:

kdesrc-build konsole --no-src --resume-from konsole

Those arguments will tell kdesrc-build to not update the source code after you applied the patch, and to not build any dependencies.

If it didn't compile, that's reason alone to reject the patch! Go to the web UI and report your findings, and apply a "Request Changes" status.

Perform QA

If it did compile, then it's time to perform QA, because it's important to thoroughly test patches to ensure that bad code and regressions don't slip in. This is the entire purpose of having a review infrastructure; it is very important.

Next, execute the Test Plan that the submitter wrote. If the patch does not have a Test Plan, request one. Does it all still work for you? If not, return to the web UI and Request Changes, writing a detailed comment explaining what didn't work. It is permissible to do this even if you have not been specified as a reviewer! Anyone can reject a patch on the grounds that it does not work, does not do what it says it does, or causes regressions.

If the original Test Plan succeeds, try to break the patch. Here are some ideas:

Try the program with a HiDPI scale factor (or without one) or with a different default font size

If it's a new feature, feed it unexpected input

Test related functionality

Try to break it! A good patch will handle corner cases and variations in configuration. The price of configurability is vigilant testing! We owe it to our users to test using many configurations, not just the defaults or our personal settings.

Perform code review

Note

Need a section on code review here, preferably written by a core KDE developer or another very experienced developer

Engage with the author and other reviewers

After you have run the program and evaluated the patch, it's time to leave some review comments on the webpage (which again is at https://phabricator.kde.org/<revision ID>). If you have been specified as a reviewer, or are a member of a group that has been specified as a reviewer, it is permissible to Accept the patch. But keep in mind that reviewing involves responsibility: you are giving a thumbs-up to code that will be run potentially by millions of people. If you accept and land a patch that causes regressions, you will share some of the blame. It's important to take the reviewer role seriously.

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 that are in 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.)