Phabricator

= Phabricator for OpenStack =

Adopting Phabricator for OpenStack gives us the ability to piggyback on a modern, flexible task tracker developed by an active community. There are a few compelling features, like low-cost dashboards triggered by tag-like "projects", UI review tools (Pholio), or per-user customizable automation (Herald).

That said, OpenStack has a number of use cases that Launchpad served very gracefully (at least on the bugtracker side) that we need to figure out how to solve.

Tracking affected repositories and branches
In OpenStack, one of the main uses we have for a task tracker is to track the completion of a complex task over a set of teams. There is no "Story" or "TaskGroup" in Maniphest, so everything must be represented using tasks, "projects" and/or custom fields. That leaves us with a limited set of options to track related work that needs to land in separate repositories / branches, and therefore be treated by separate teams.

(1) Using "projects" on a single task
One solution is to track all the work on a single task. You add "projects" for each affected repository 'nova, python-novaclient...) and each possible target branch (kilo, juno, no branch meaning "master"). The task is manually closed when all the needed commits are merged. Two issues with this approach: you don't really track the repository/branch combinations, and it's difficult to assess when the task is completed. To have visual indication of progress and help the human at the end of the process figure out when the task is actually completed, you would likely duplicate the "steps" in a checklist in a description field, which kind of defeats the whole purpose of having a field there.

(2) Using "projects" on dependent tasks
This solution is to create parent tasks and subtasks with the exact repository/branch "projects" combination affecting the branch. The main issue with this approach is that it can be pretty cumbersome (especially since you can't create a "parent task" easily in Maniphest), and nothing prevents the user from adding multiple repository and branch projects on a single task, resulting in confusion (especially for any tool trying to autoclose things).

This is still probably still the best solution we have.

(2b) Using custom fields on dependent tasks
This solution is similar to the previous one, except you use custom fields to describe the repository and the branch affected. You solve the duplication issue: a task will only have one repository and one branch. The drawbacks is that it requires custom development, and the approach remains cumbersome for the same reasons as above.

(2c) Preventing multiple repo/branch "projects" to be selected at the same time
Like the previous one, this solution avoids the duplication issue: a task will only have one repository and one branch. It's slightly more elegant than using custom fields, since you can piggy-back on all the benefits of "projects" in terms of display/search etc. It requires the development of a specific patch that would have to get accepted upstream or be carried on our side.

(3) Using a single task and track affected projects/branches in the description
After reaching out to the Phabricator people, it appears our use case (tracking the various commits that end up being necessary to solve a task) is really change/release management, not task tracking. They have a specific tool coming up to do that (called Releeph), so they are unlikely to push any new feature in that direction. One option they suggested was to track the breakout of affected projects/branches in a table that we would display on top of the description. We could autogenerate that table based on Gerrit data (using a single topic linking the review to the task). See http://15.126.194.141/T1399131 for an example of how it could look.

Request / track a backport
The first use case is one of a bugfix in master that you would like to request (and track) the backport of in a stable branch. The trick here is that the backport is a follow-up task, the fix must be merged in master first.


 * Using model (1) you would add multiple branch "projects" to the same task, to indicate the need for a backport. That's convenient and displays well, but it's difficult to track the completion of the task or to autoclose it.
 * Using model (2) you would consider the main M task to be "master" by default, and create a "follow-up" backport task B that will block on task M. It's doable, but the UI is non-trivial: you need to create B, set the right projects on it, then search for and add A as a "subtask" of B. We'd likely want to develop a specific "follow-up" action to do that in one step, and carry the resulting patch if upstream doesn't want it.
 * Using model (3) you would request the backport like in (1) and once posted it would be tracked using the Gerrit-driven update.

Tracking completion of horizontal work
The second use case is the workflow of the Vulnerability Management Team, or any horizontal team needing to land a given piece of work in a large set of repositories and branches.


 * Using model (1) is not a good answer to that case, since the value of the task tracker here is to make sure you cover all the bases and don't let any project fall into the cracks. You would likely track the work in a checklist in the task description, because there is no way to track a list of affected repo/branch combinations in that model. It would also reduce the potential for human error while increasing the human cost in maintaining the status of the task.
 * Using model (2) you would consider the main A task to be the coordination task (the "ossa" task for the VMT), and create subtasks for each affected repo/branch combination. One issue here is that the repo/branch does not appear in the subtask list on the main task, making it likely you have to drill down to get an idea of what each task actually means. To solve that issue we could work on a patch to display repo/branch in the subtask lists.

Incoming bugs
Launchpad is project-centric: you can't "file a bug", you have to pick a project. While that makes for a poorer user experience, it conveniently avoided the need to have "default bug triaging teams" which would go through list of untriaged bugs and direct them to the affected components and teams.

It is likely that if we switch to Phabricator we would have to rely on Herald rules to set a few projects by default based on keywords in titles or descriptions, and a team to deal with the leftovers.

New idea: we should have a specific page for bug submission, that forces users to pick at least one project (repository/blue color). Would allow us to drop extra fields and add boilerplate information

Project taxonomy
Phabricator "Projects" are like tags, but to get consistency you can't let users directly create them. Instead we'll likely do what Mediawiki did and have a group of people create them upon request, following established rules for categories.

Here are the proposed categories:
 * Repositories
 * Service projects: Briefcase + Blue
 * Library projects: Folder + Blue
 * Other projects: Cloud + Blue
 * Branches
 * Release / Stable branches: Goal + Orange
 * Feature / Bug branches: Experimental + Yellow
 * Teams: Team + Green
 * Tags: Tag + Grey
 * Umbrella (ad-hoc groups/projects): Umbrella + Violet

API limitations
Conduit, the Phabricator API, does not fully expose all the attributes of all the objects. Here are a few limitations that will really affect us:
 * maniphest.createTask and maniphest.update do not let you define related tasks, so you can't create a subtask (or a parent task) using the API. This is one of the issues described in https://secure.phabricator.com/T5873

= Likely customizations =

"Add supertask"
or add follow-up task... useful for backports

Page for submitting bugs
To make sure at least one project gets selected