Homepage of Timotheus Pokorra

This is an updated version of the post from July 2015: https://www.pokorra.de/2015/07/submitting-patches-to-kolab-via-phabricator/

For a description of phabricator, see the post from July 2015.

Here are the updated instructions for using arcanist with CentOS7:

yum install git vim php-cli python-pep8
# this does not work because of contradicting dependancies:
# wget https://obs.kolabsys.com/repositories/Tools/CentOS_7/Tools.repo -O /etc/yum.repos.d/kolab-tools.repo
# yum install arcanist
git clone https://github.com/phacility/libphutil.git
git clone https://github.com/phacility/arcanist.git
export PATH=$PATH:/root/arcanist/bin/
arc set-config default https://git.kolab.org
arc install-certificate 
# go to https://git.kolab.org/conduit/login/ and copy the token and paste it to arc

Now get the repository you want to work with, eg. pykolab:

export PATH=$PATH:/root/arcanist/bin/
git clone https://git.kolab.org/diffusion/P/pykolab.git
cd pykolab
# do your changes
# vi pykolab/auth/ldap/__init__.py
git commit -a
arc diff            # Creates a new revision out of ALL unpushed commits on
                    # this branch.

Now you have a new Differential revision, in my example at: https://git.kolab.org/D559

Just before the Kolab Summit, at the end of April 2015, the Phabricator instance for Kolab went online! Thanks to Jeroen and the team from Kolab Systems who made that happen!

I have to admit it took me a while to get to understand Phabricator, and how to use it. I am still learning, but I now know enough to write an initial post about it.

Phabricator describes itself as an “open source, software engineering platform”. It aims to provide all the tools you need to engineer a software. In their words: “a collection of open source web applications that help software companies build better software”

To some degree, it replaces solutions like Github or Gitlab, but it has much more than Code Repository, Bug Tracking and Wiki functionality. It also has tools for Code Review, Notifications and Continuous builds, Project and Task Management, and much more. For a full list, see http://phabricator.org/applications/

In this post, I want to focus on how you work with the code, and how to submit patches. I am quite used to the idea of Pull Requests as Github does it. Things are a little bit different with Phabricator. But when you get used to it, they are probably more powerful.

Starting with browsing the code: there is the Diffusion application. You can see all the Kolab projects there.
It also shows the “git clone” command at the top for each project.
Admittedly, that is quite crowded, and if you still want the simple cgit interface, you get it here: https://cgit.kolab.org/

Now imagine you have fixed a bug or want to submit a change for the Kolab documentation (project docs). You clone the repository, locally edit the files, and commit them locally.

You can submit patches online with the application Differential: Go to Differential, and at the top right, you find the link “Create Diff“: There you can paste your patch or upload it from file, and specify which project/repository it is for. All the developers of that repository will be notified of your patch. They will review it, and if they accept it, the patch is ready to land. I will explain that below.

Alternatively, you can submit a patch from the command line as well!
Let me introduce you to Arcanist: this is a command line application which is part of Phabricator, that helps with integration of your git directory with Phabricator. There is a good manual for Arcanist: Arcanist User Guide
Arcanist is not part of Fedora yet (I have not checked other distributions), but you can install it from the Kolab Tools repository like this, eg on Fedora 23 (see Kolab Docs: Setup your Development Environment for details):

# import the Kolab key
rpm --import "http://keyserver.ubuntu.com/pks/lookup?op=get&search=0x830C2BCF446D5A45"
wget https://obs.kolabsys.com/repositories/Tools/Fedora_23/Tools.repo -O /etc/yum.repos.d/KolabTools.repo
yum install arcanist
 
# configure arcanist (file: ~/.arcrc) 
arc set-config default https://git.kolab.org 
arc install-certificate 
# go to https://git.kolab.org/conduit/login/ and copy the token and paste it to arc

Now you can create a clone of the repository, in this example the Kolab Documentation:

git clone https://git.kolab.org/diffusion/D/docs.git
# if you have already an account on git.kolab.org, and uploaded your SSH key to your configuration:
# git clone ssh://git@git.kolab.org/diffusion/D/docs.git
cd docs
# do your changes
# vi source/installation-guide/centos.rst
git commit -a
arc diff            # Creates a new revision out of ALL unpushed commits on
                    # this branch.

This will also create a code review item on Differential!

For more options of arc diff, see the Arcanist User Guide on arc diff

By the way, have a look at this example: https://git.kolab.org/D23

Now after your code change was reviewed and accepted, your code change is “ready to land”.
It depends if you have write permissions on the repository. If you don’t have them, ask on IRC (freenode #kolab) or on the kolab developers’ mailinglist for someone to merge your change.

If you have push permissions, this is what you do (if D23 is your Differential id):

# assuming you have Arcanist configured as described above...
arc patch --nobranch D23
# if we are dealing with a branch:
# arc land D23
git push origin master

I hope this helps to get started with using Phabricator, and it encourages you to keep or start submitting patches to make Kolab even better!