Team Practices Group/Phabricator tips

Introduction
NOTE: This page is a sandbox. Once the content is developed enough to be usable, it will be copied, merged, folded, or migrated over to one or more of the existing WMF Phabricator documentation pages, such as Phabricator/Project management.

The goal of this page is to explain at a higher ("why") level how best to use Phabricator. Eventually this page should reflect the consensus opinions of the Team Practices Group. Step-by-step details for "how" to perform tasks in Phabricator can be left to other pages.

Major concepts
Phabricator has 3 main top-level objects: Users, Tasks, and Projects.

User
Each user has a profile. Users can Join or Subscribe to Projects, and can be Subscribed to or Assigned to Tasks.

Task
Tasks are the heart of the system, and mostly behave similarly to issues in other issue-tracking systems. Each Task is uniquely identified by its ID, which is in the form Txxxxx. Each task has a Title, Status, Assigned To, Priority, and Description, Visibility, Editability, and Security. Each also has a list of CC (Subscribers) and a list of associated Projects. Attachments can be added as part of a Description or Comment.

By conscious decision, Tasks in the WMF instance have very few fields, so for example they do not have "OS/Platform" or "See Also" fields. Requests to add additional fields are likely to be rejected, with the advice to instead include that information in the Description or in a Comment.

A task's status can only be one of:
 * Open
 * Resolved
 * Stalled
 * Declined
 * Invalid
 * Duplicate

These statuses are unrelated to the implied state that a task might be in, based on which column it is in any workboards. So for example, a task could have a status of "Open" but be in the "Done" column on a workboard. Or it might have a "Resolved" status but be in an "In Progress" column in a workboard. Although these cases are possible, they might (or might not) indicate that the task was managed incorrectly.

Side note: You can't directly set a status to "Duplicate". Instead, you have to "merge duplicates in" and define the number of the duplicate task, and the status will be updated automatically.

Project
Projects are unlike projects in most issue-tracking systems. See below.

Projects
Unlike most issue-tracking systems, Phabricator Projects are really a form of "tag". Whereas typically a Task is contained by a single Project, in Phabricator a Task can be in any number of Projects. This is fundamental to the way Phabricator works, so it is important to understand all the implications.

Phabricator does not yet support nested Projects, so all Projects are currently at the top level. Naming conventions are used to communicate the intention of hierarchical relationships.

Types of projects
Phabricator Projects can represent a "Project", in the normal sense of the word. But the Project feature is used in a variety of other ways. A Project can be any of:
 * Team (e.g. Security) (Purple)
 * Generally a sub-team would be handled as a Project or Component instead
 * Umbrella (e.g. Android App) (Blue)
 * Larger non-team-centric projects
 * Component (e.g. Cirrus Search) (Blue)
 * Can also be sub-components
 * Sprint (e.g. ToolLabs-Q4-Sprint-1) (Green)
 * Note that a "Sprint" Project has magic powers (see below)
 * Release (e.g. MediaWiki 1.25) (Orange)
 * See below
 * Tag (e.g. i18n) (Yellow)
 * Can be a cross-cutting concern, such as Security or Design, or a category like Epic or Easy

The icons and colors associated with different types of projects are a WMF convention, not enforced by software.

Workboards
Workboards allow organizing Tasks in columns, and arranging them via drag-and-drop. Each Project can only have a single Workboard. Columns can be added, removed, and rearranged via the Manage button in the upper-right corner of the Workboard view.

Typical uses of workboards

 * Workflow
 * Typical columns would be along the lines of TODO, DOING, DONE
 * This supports both Scrum-style sprint iterations, and Kanban-style continuous work
 * Roadmap
 * Each column might represent a target release, or general timeframe (e.g. "2016")
 * Categories
 * Columns might group Tasks by component, functional area, or even complexity

Workflow workboards
Although the basic structure is TODO, DOING, DONE, there is a lot of flexibility as to the number of columns, and their names. Here are some possible examples with variations in wording:


 * TODO, To Do, Backlog, Product Backlog, Sprint Backlog, Inbox
 * Selected, Next, Ready, Ready For Work
 * DOING, Doing, In Progress
 * Needs Review
 * DONE, Done, Completed, Finished
 * Blocked, Waiting, In Discussion

"Sprint" workboards
Phabricator has a special case of Workboard known as Sprint. Sprints behave like regular Workboards, but add functionality. Notably, Tasks in a Sprint have a new Story Points field, which can hold an estimate. Sprint Workboards add up these estimates per column, and these estimates are used in the Burndown Chart feature.

Sprint Workboards would almost always be configured to represent Workflow. However, the only way for a task to have an estimate field is for it to be in a Sprint project. So if a team wants to estimate all their tasks, they might flag their project as a "Sprint" even if it didn't have any workboard, or if the workboard was being used for something other than to track workflow.

Teams and multiple workboards
Although each Phabricator Project can only have a single Workboard, most teams will manage multiple Workboards. Most teams will have at least one workflow workboard, to track tasks as they are worked on and then completed. Here are some examples of typical team uses of workboards:

Simplest (single board)
A team might directly use its Team Project Workboard to track workflow. Tasks might move through columns like INBOX, IN PROGRESS, IN REVIEW, and DONE. Note that as of 2015-04-06 it is not possible for a "Project" project to also be a "Sprint", so the team would not be able to to use the Story Points field.

Typical Scrum
A team might use its Team Project Workboard as a roadmap, with columns like INBOX, NEXT SPRINT, THIS QUARTER, NEXT QUARTER, LATER. Then, at the start of each sprint, they would create a Sprint Project, and add to its Workboard the tasks representing the sprint backlog. By the end of each sprint, all the tasks in that sprint's Workboard should be in the DONE column. Old Sprint Projects would typically be archived (so would no longer be visible to normal users).

If the team has multiple sub-teams or components, each of those will have its own Workboard. The team might configure those Workboards to group tasks by category. It would be possible to set up roadmaps at that level, but managing multiple levels of roadmaps containing the same tasks could be redundant. In that case, one option would be to keep the low-level tasks at the component/sub-team level, and only bring Epics and "Tracking" Tasks up to the team's main Workboard.

Typical Kanban
Very similar to the Simple Scrum case, the team might use its Project Workboard as a roadmap. The team could just create a single permanent Sprint Workboard to act as the Kanban (workflow) board forever, but it would probably be better to rotate out a new Kanban "Sprint" Project periodically (e.g. quarterly).

Tasks and workflow
Each Phabricator Workboard has a column flagged as "Default", and any new task added to that Project will start off in that column.

Blocking tasks
Tasks can block, or be blocked by, any number of other tasks. This feature can be used to accomplish a few different things:
 * Blockers. A task might simply be blocked by another task, representing a dependency.
 * Subtasks. A parent task would be blocked by its subtasks. (There is no other way to mark parent/subtask relationships).
 * Tracking. A "workless" task blocked by several tasks might be tracking a collection of tasks within a release or other time period (see below).
 * Approval. Several tasks (such as draft team goals) might be blocked by a single task which represents the draft tasks getting approved, after which those draft goals are now real goals.

NOTE: There is a "Create Subtask" feature. In addition to setting up the correct blocking/blocked-by relationship, it also caries the CC (subscription) list into the new subtask. Once the subtask has been created, it is simply a blocking task. The explicit "subtask" state is not preserved.

Prioritization
Each Task has an Priority field, which is reflected in the sidebar color of Tasks that appear in Workboards. Note that this Priority is inherent to the Task, and thus will be the same in every Project and Workboard that task appears in.

Within a Workboard, Tasks can be arranged in a priority order within a column. Choose "Natural" sort, and then drag and drop Tasks up or down within a column. This allows a groomed backlog to be sequenced by priority, or could indicate the urgency of items in a "Needs Review" column. Note that Workboard columns can also be sorted by the underlying Priority field, so while discussing a Workboard with someone not in the room, it is best to agree on and use the same sort order to avoid confusion.

Assignment
Each Task may be assigned to one person. As with Priority, this is inherent to the Task, and affects every Project that Task is in. So it is impossible to have a Task assigned to Robin in one Project, but to Kim in another. The assigned person is displayed as part of the Task card in each Workboard.

Some teams might choose to assign Tasks to people while the Tasks are in a TODO column. Others would have people assign Tasks to themselves only at the moment that they are moving them from TODO to DOING. Assigning a Task to yourself before you are ready to work on it is a form of "cookie licking."

After the main work on a Task is finished, there are 2 main patterns for assignment:
 * The Task remains assigned to whoever did the work, as that task's permanent owner
 * The Task gets reassigned to whoever needs to work on it next

So for example, after code has been written, it might needs a code review from some specific person. In the second case, the Task would be assigned to that person, making it clear who is responsible for moving that task forward. Obviously if there are multiple possible code reviewers, that model would not work. Later, if the issue were waiting for someone to test it, or deploy it, or to run some specific task necessary for the Task to be completed (like a re-index), the Task could be assigned to that person. A team might have a policy that completed tasks should get assigned back to the person who originally created them, so that person can verify that their needs were met, and the task is ready to be closed.

"Done"
Each Task has a Status field, which includes the state of Resolved. Resolved tasks are often hidden from Workboards, and when they are displayed, they appear grayed out and struck out. Other statuses include Open and Stalled.

Note that this Resolved status is inherent to the Task, and so will affect that Task's appearance and behavior in every Project (and Workboard) it is in. This is independent of which column a Task might be in, in any given Workboard. So a Task could be Open, and could be in the DONE column of one Workboard, but the DOING column of another. It could also be in the 2016 column somewhere else.

As a result, it is important not to mark a task Resolved until it is considered done by ALL of the projects it is in. It's fine to move a Task to your own Workboard's DONE column, but before you mark a task Resolved, ensure that no other project still wants to keep tracking its progress.

"Tracking" tasks
This term was brought over from Bugzilla, where it had a specific meaning: A task which was blocked on other tasks, but which itself did not represent any work, and which was not tied to a specific release/date. An example might be a Task named "Clean up the documentation", which might then have a variety of subtasks, each of which would describe specific work to be done. These "Tracking" Tasks tended to stick around for a long time (or forever), as their subtasks would get resolved but new ones would get created. In Phabricator, it would be better to create a Project (tag) to categorize this type of work.

Note, however, that there are other types of work-less umbrella tasks which do still make sense in Phabricator. Notably, "Release" tasks. An upcoming release could be represented by a Task, which lists as subtasks (aka blocking tasks) all the actual work tasks which are targeted for that release. Once the release goes out, it can be resolved. A similar use would be to have a task which represents a teams overall goals for the quarter, and then each goal might (or might not) be a blocking subtask.

Other resources

 * Phabricator/Project management
 * A multi-purpose page which seems mostly aimed at team leads or process facilitators. Of all the resources here, it is closest in intent to this page. Mentions Kanban and sprints.


 * Wikipedia entry about Phabricator
 * Contains general information about the product.


 * Wikipedia entry about reporting Wikipedia bugs
 * Wikipedia-centric information on phab. Lots of links to other pages, although several have additional information as well (some of which might really belong inside those links).


 * http://phabricator.org/
 * Official product site.


 * Phabricator
 * This root page is still heavily focused on the WMF transition into Phabricator.


 * Phabricator/Help
 * Reference guide, focusing on “How”, not “Why”


 * Talk:Phabricator/Help
 * “The” place to ask the WMF phab team about how to use the tool. Technical problems/suggestions can be submitted as Tasks for the Phabricator project. Process questions could be addressed to the Team Practices mailing list.


 * Phabricator/FAQ
 * More than half of the questions relate to the migration, and much of the rest relates to getting set up initially. Very little information for existing phab users.


 * Phabricator/Creating and renaming projects
 * Mechanical description of the nuts and bolts of getting a project created. “How”, not “Why”. Has a useful list of all the project types, which probably belongs (or at least should be duplicated) elsewhere.


 * Phabricator/Permissions
 * Good brief summary of phab user roles and what they can do.


 * Bug_management/Phabricator etiquette
 * General bug-reporting etiquette, aimed primarily at end-users, and not so much at developers, product owners, or process facilitators. Not much information specific to Phabricator.


 * Bug management/Bug report life cycle
 * Mediawiki-specific description of the life cycle of a defect report in Phabricator. Includes some advice that I am currently skeptical about (specifically, that an issue should be Resolved as soon as the code is merged, rather than waiting until it has been released).


 * Bug management/How to triage
 * WMF-specific guidelines for triaging bugs in Phabricator. Probably more useful for a global bugmaster than for individual team members.


 * How to report a bug
 * Mostly general advice on bug-reporting, but with Phabricator-specific HOWTO recipes.


 * Phabricator/Projects
 * A wiki page version of https://phabricator.wikimedia.org/project/query/all/ which is generated by a script. It’s not (yet) clear how frequently it is updated.


 * Phabricator
 * Internal highly technical details about WMF’s phab instance.


 * https://secure.phabricator.com/book/phabricator/article/remarkup/
 * Reference guide to text formatting commands available in phab descriptions and comments.


 * IRC channel where phab (and presumably other tool) issues are discussed.
 * IRC channel where phab (and presumably other tool) issues are discussed.