Phabricator/Tāi-bé
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.
Teh Uikimitia ê Phabricator
Wikimedia uses a Phorge (previously known as Phabricator) instance with minimal changes from upstream because maintaining local patches is cumbersome. The exceptions to this are extensions, which live in a separate repository 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.
Uikimitia Phabricator tshò-ngōo kang-tsok liû-tîng
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-upstream for general Phabricator/Phorge issues. Software bugs and enhancement requests will typically fall in this second category.
The Phabricator-upstream workboard shows the process that tasks go through before being created upstream:
- Backlog: This is where new tasks land by default. Stalled tasks can also be found here.
- Ready to go: Tasks which could potentially go into the Phorge's bug tracker. When doing so, you must follow:
- Upstreamed: Tasks which have been reported upstream. For some tasks this might refer to the old upstream (secure.phabricator.com until 2021), for some tasks this might refer to the current upstream (we.phorge.it).
- Solved upstream: The related upstream Task has been closed, probably with a related commit. To reflect this specific change in Wikimedia Phabricator, it may be still necessary to plan an upgrade in Wikimedia.
- Feedback from Upstream: An upstream discussion is still required or still pending.
Once a task has been published upstream, upstream developers respond with their assessment, and suggestions for how the feature should be implemented. At this point a developer can start with the implementation.
In some cases, the upstream developers will decide a feature does not fit into their plans. In this case, the task in Wikimedia Phabricator is moved from the #phabricator-upstream project to the #phabricator project, and ends up back into the discussion stage: is this feature important enough to maintain local patches? Once this has been decided, one can start with the implementation.
To increase the chances that your code will be approved, and to avoid inconvenience, contact Phorge or the WMF maintainers to discuss about a possible implementation.
Contact Phorge (upstream)
- Ask a new question about Phorge
- Browse questions and answers about Phorge
- See the Tag #affects-wikimedia in Phorge
Kio̍k-pōo piàn-huà
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. It's significantly less work to maintain a phabricator extension, as long as care is taken in avoiding the use of particularly new / unstable APIs from phabricator's core. Although extensions don't require merging and potential code conflicts, they do require testing each time we pull in upstream changes. Phorge does not have any frozen APIs which are deemed safe to depend on.
The current code of the Wikimedia Phabricator instance itself:
- https://gitlab.wikimedia.org/repos/phabricator/phabricator
- https://gitlab.wikimedia.org/repos/phabricator/arcanist
The current locally-maintained extensions are:
- Several customizations in one code repository, such as the MediaWiki OAuth extension (not upstreamed; see the Differential revisions and commits at https://secure.phabricator.com/T5096), Security related code, the MediaWiki Userpage field on Phabricator user pages, etc.
- Antivandalism, still in Gerrit and to be moved to GitLab.
Uī-tì phuè-tī
Most of the configuration is set through the web interface. Defaults (shared between https://phabricator.wikimedia.org and e.g. https://phabricator.wmcloud.org/) are set using either the puppet maniphest or the Scap template (see phab:T239355).
Siat-tīng
Another way to get set up is by using MediaWiki-Vagrant using the 'phabricator' role. Follow the steps on MediaWiki-Vagrant to install MediaWiki-Vagrant, then enable the phabricator role using
vagrant roles enable phabricator --provision
- Thong-kuè URL kia̍t-tshú Phabricator ê si̍t-lē: http://phabricator.local.wmftest.net:8080/
- The Phabricator install is located in `/srv/phabricator/` (?) on the VM.
Sú-iōng si̍t-giām-sik (SGS) hi-gí-ki (HK)
If you know how to spin up a VM on Cloud VPS, 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 https://phabricator.wmcloud.org/.
Uì Bugzilla, RT, Mingle, Trello kàu Phabricator ê î-suá tāi-bé
The scripts that Wikimedia used for migrating its Bugzilla and RT data to Phabricator are available. Note that the migration code is not bug-free and that it was only written and used for the specific configurations of Wikimedia's tools. Also note other migration scripts, e.g. the GStreamer project used a phill script by Emanuele Aina to import their data from Bugzilla into Phabricator in 2015.
Data was migrated from Mingle to Phabricator via a script available in phab:P129.
The scripts to migrate data from Trello to Phabricator are available. Iú-kuan siông-sè sìn-sit, tshiánn tsham-ua̍t phab:T821.