Phabricator/Code

This document describes the development process for Wikimedia's Phabricator instance. Phabricator is written in PHP, just like MediaWiki, which should help in getting started with development. In this document, we will first take a look at how Wikimedia is using Phabricator, and what to expect during development. Afterwards, there are a few notes on how to get started with the actual development.

Phabricator at Wikimedia
Wikimedia uses a Phabricator instance with minimal changes from upstream. The reason for this is the high development pace of the upstream developers – maintaining local patches is cumbersome. The exceptions to this are extensions, which live in a separate directory and thus do not need regular merges. Any other changes thus have to pass through upstream. This sounds like a major obstacle, but in practice, the upstream maintainers are very prompt in responding to suggestions.

Wikimedia Phabricator bug workflow
It is helpful to understand the life cycle of a bug before taking on one of the tasks. There are two projects: #phabricator for WMF-specific bugs and #phabricator.org for general Phabricator bugs. Software bugs and enhancement requests will typically fall in this second category.


 * 1) New bugs in #phabricator.org then move to a discussion stage to clarify the request.


 * 1) The request is then 'upstreamed' (copied to the phabricator.org bug tracker)


 * Only high-priority requests are marked with the #wikimedia tag.


 * 1) The upstream developers then respond with their assessment, and suggestions for how the feature should be implemented.


 * At this point one can start with the implementation.


 * 1) In some cases, the upstream developers will decide a feature does not fit into their plans. In this case, the bug is moved from #phabricator.org to #phabricator, and ends up back into the discussion stage: is this feature important enough to maintain local patches?


 * Once this has been decided, the patch will move to 'Ready to go', and one can start with the implementation.

To prevent disappointment, please do not start with the implementation until it's clear either upstream or the WMF maintainers will accept your patch.

Local changes
As mentioned in the previous section, we try to keep local patches to a minimum. There are limited resources available to maintain patches, and to merge them with changes from upstream. Any local patches therefore have to be discussed within the #phabricator project.

The current locally-maintained parts are:


 * The MediaWiki OAuth extension (in the process of being upstreamed; see the Differential revisions and commits at https://secure.phabricator.com/T5096).


 * [https://git.wikimedia.org/blob/phabricator%2Fextensions.git/master/SecurityPolicyEnforcerAction.php Security extension] (Wikimedia's specific development while upstream implements their solution for private projects).


 * [<tvar|git>https://git.wikimedia.org/blob/phabricator%2Fextensions.git/master/MediaWikiUserpageCustomField.php</> MediaWiki Userpage field]

Site configuration
Most of the configuration is set through the web interface. Defaults (shared between <tvar|phab>https://phabricator.wikimedia.org</> and e.g. <tvar|wmflabs>https://phab-01.wmflabs.org</>) are set using the [<tvar|maniphest>https://git.wikimedia.org/blob/operations%2Fpuppet.git/production/modules%2Fphabricator%2Fdata%2Ffixed_settings.yaml</> puppet maniphest].

Setting up
The easiest way to get set up is by using vagrant>MediaWiki-Vagrant</>|Vagrant. Following these steps should help you get started:


 * [<tvar|scm>http://git-scm.com/</> Get Git]


 * Get NFS if it is not already installed. It is usually already installed in MacOS X. In Ubuntu, use <tvar|code> </>.


 * [<tvar|virtualbox>https://www.virtualbox.org/wiki/Downloads</> Get the latest VirtualBox]


 * [<tvar|vagrant>http://www.vagrantup.com/downloads.html</> Get the latest Vagrant]


 * Run the following commands in a shell:


 * Wait until the VM is built. You can then visit your Phabricator instance at <tvar|phab-link>http://127.0.0.1:8080</>, and ssh to the VM on <tvar|ssh>ssh://vagrant:vagrant@127.0.0.1:2222</>.


 * The Phabricator install is located in `/phabricator/instances/dev/phabricator` on the VM. To edit and submit a patch:

Congratulations, you have submitted your first patch!

Using a Labs VM
If you know how to spin up a VM on Labs, and have the rights to do so, you can create an instance with the `phabricator::labs` role. This should give you a basic setup with the same configuration as <tvar|wmflabs>https://phab-01.wmflabs.org</>.

Migration code from Bugzilla/RT to Phabricator
The [<tvar|git>https://git.wikimedia.org/tree/phabricator%2Ftools.git</> scripts that Wikimedia used for migrating its Bugzilla and RT data to Phabricator are available]. Note that the migration code is [<tvar|blogs>https://blogs.gnome.org/aklapper/2014/12/17/welcome-phabricator/</> not bug-free] and that it was only written and used for the specific configurations of Wikimedia's tools.