Phabricator/Project management

Good practices for Phabricator project management. Coming soon. See phab:T558

You have a project in Phabricator that you maintain or manage. Now what? There are many possible ways to run project successfully. This document focuses on the common expectations for Wikimedia projects. Following this guideline should help you being productive and interacting better with other contributors and projects in the Wikimedia community.

Why use Phabricator for managing your project?

Wikimedia engineering teams and Wikimedia-related projects are encouraged to use Phabricator for managing their project(s). This keeps projects more visible by managing them in the same place as one another as well as where issues are reported. This also makes collaborating between and across teams easier, as it is trivial for tasks to be shared and moved around from team to team, project to project. Further, it is particularly valuable to be able to manage your workflow in the same place where bugs/issues are reported. This eliminates the need for hacks like Bingle and keeps the visibility of bugs/issues high by not spreading teams' focus across multiple tools.

Unlike most of the other project management tools in use by Wikimedia engineering teams/projects, Phabricator is an open source project primarily written in PHP. The Phabricator team is highly responsive to our needs, and when they can't/won't meet our needs... well, patches welcome :) The more we use Phabricator, the more we understand what we need that might be missing, the better we can help make the tool.

Tasks

Tasks are the basic building block of Phabricator. A Phabricator task is something that can define things like bugs, user stories, feature requests, etc. While a task can represent different kinds of things, all tasks have certain properties, like title, creator, assignee, description, tags, projects, etc. Unlike many other project management and issue tracking tools, a task can have a one-to-many relationship with 'projects' - that is, a single task can be associated with more than one 'project'.

Scope of tasks

The basics: Phabricator/Help#Creating a task.

Tasks need to describe an achievable objective. Ideally, tasks are defined with a scope that can be resolved by one person with a decent amount of effort. Huge tasks that take several people and several days will be more manageable when you identify the 'subtasks' required to complete them. Trivial 'subtasks' that one person can complete in a moment but should be documented can be just added as a checklist in a description of the main task. A good principle to follow is that a task should be completable within a single iteration - for teams/individuals not working with iterations, think ~2 weeks maximum. If a task is larger than this, it should be broken down into smaller tasks.

Team-level goals are often called "Epics". There is an "epic" tag, which we use for goals we identify in the quarterly planning process.

Invalid tasks

If a task fails defining an actionable objective (e.g. never-ending tasks, support questions, generic complaints...) they might be resolved as Invalid. Users resolving a task as Invalid should explain their reasons in a comment (also see the Bug report life cycle). Tasks are fully editable, and if the causes for the Invalid resolution have been addressed, they can be reopened.

Use plain language, define actions and expected results

Since tasks are the primary building block of Phabricator and they are generally public and visible to everyone, they are valuable ways of communicating not just with people who will be completing the work, but with other stakeholders as well. It is considered best practice to keep tasks written as plainly as possible - in language that can generally be understood by most people. One easy way to achieve this is by describing an action taken (or to be taken) and the desired (or expected) result - and there's a handy pattern for achieving this known as 'given/when/then'. As an example:

Given that I am viewing and article on English Wikipedia and am not logged in,
When I click the link from the left navigation that says 'Random',
Then I am taken to a random article on English Wikipedia in the main namespace.

In the case of a bug, say 'Random' link isn't working, you could include the language above and add to it:

This is not currently working as expected. Clicking the 'random' link from the left
navigation menu currently takes me to the article 'Entropy' every single time I
I click on it. However, when I am logged in, the 'random' link works as expected'.

As opposed to:

Special:Random is broken

The former example is generally understandable by anybody, the latter may only make sense to a MediaWiki software engineer who is intimately familiar with Special:Random. Of course you do not need to follow the formula specifically if you don't want to, but hopefully the examples make the principle clear: define tasks in simple language and in a way that can be understood by a broad audience. Also see How to report a bug.

Assigning tasks

In principle, a task gets assigned to whomever will take ownership of it. Even in formal teams with a product owner, the idea is that the PO says what needs to get done, and the team itself figures out whom will work on what.

You should have a task assigned to yourself only when you are prepared to work on it. There is no use in having tasks assigned that haven't been or won't be touched for a long time. See also: cookie licking.

Setting task priorities

One task can have only one set priority at a time. Priority should normally be set by product managers, maintainers, or developers who plan to work on the task, or by the bugwrangler or experienced community members, not by the reporter filing the bug report or by outside observers.

When an assignee is already set for a task, its priority should not be changed without agreement of the assignee or development team first.

In the event the priority of a task is repeatedly and inappropriately set, the task may become protected and made modifiable only by specific people.

Priority levels

Wikimedia Phabricator offers these priority levels:

• Needs Triage - Default option, signaling that the priority is to assign a priority.
• Unbreak Now! - Something is broken and needs to be fixed immediately, setting anything else aside.
• High - Someone is working or planning to work on this task soon.
• Normal - Less priority than High, but you are still planning to work on it.
• Low - Less priority than Normal, but you are still planning to work on it.
• Needs Volunteer - You are explicitly saying that you don't plan to work on this task, even if you would be happy if someone does.

Usually the tricky part is to handle High - Normal - Low in a consistent way, especially for tasks that are still unassigned. One way to approach this:

• High priority for tasks committed for the current sprint, or that need to find an owner who can start working on them soon.
• Normal priority for tasks that are not critical for the current sprint or candidates for a next sprint.
• Low priority for tasks that we can live without, usually sitting in the backlog, sometimes added to a sprint.

Limiting high priority tasks assigned to a single person

While priority setting and assignment are generally up to teams and individuals to figure out, it is not appropriate for a single person to be assigned more than a few open High priority tasks. As a rule of thumb, limit High priority task assignments for a single person to three, five in exceptional times.

Associating tasks with projects

A task in Phabricator can be associated with multiple 'projects'. Any Phabricator user will be able to create a task in a 'project' corresponding to the old bugzilla "Component", for example MediaWiki-extensions-Flow. The one task can be associated with additional 'projects': tags such as easy or design, and project management boards such as Flow-design-backlog or sprint-Flow-current.

Tasks cannot be worked on yet

Certain tasks might not be actionable until an action has been performed outside of the task itself.

If a task depends on another task in Phabricator, you should set the number of that other task under "Edit Blocking Tasks". Afterwards, the other task will be displayed under "Blocked by".

If a task depends on a third party (e.g. upstream developers or further information from the reporter which has not responded), you can explicitly set the status to "stalled" (also see the Bug report life cycle).

Closing a task

Similar to setting priorities, a task should only be closed by the assignee or someone from the team responsible for the task (e.g. the team's product manager), and in the case of bugs, by the bugwrangler or experienced community members, not by the reporter filing the bug report or by outside observers.

A task can be closed as Resolved, Declined, or Invalid. It can also be merged as a duplicate of another task. (details)

In the event a task is associated with multiple projects, care should be taken to coordinate the closing of a task with relevant stakeholders.

In the event a task is repeatedly closed inappropriately, the task may become protected and made closable only by specific people.

Projects

'Projects' are the basic organizational method in Phabricator; they are a way to organize tasks and manage workflow. A 'project' can be imagined in many different ways - that is, a 'project' in Phabricator is much more flexible and open-ended than you might otherwise expect. You might create a 'project' in Phabricator to organize all of the work and workflow for a particular product, a single iteration or work sprint for your team, to provide a custom view for tasks in a bunch of other 'projects', etc. In short, a 'project' in Phabricator is simply a tag that can be applied to tasks, which you can then use to visualize and track those tasks in different ways.

This article will use single quotes around the word 'project' to differentiate the concept of a 'project' in Phabricator from standard uses of the word (e.g. a general software engineering project in real life).

Creating/renaming projects

The basics: Phabricator/Creating and renaming projects.

Organizing your projects

Many teams and many products require more than one 'project' in order to efficiently organize their activity. A team might organize their work in sprints, while a product might be organized in components. In these cases, sprints and components would get their own projects.

All projects are at the same level in Phabricator. To denote a hierarchy between projects, you can only do this with the project names, i.e. Cool-Project vs Cool-Project-Some-Component. Proper subprojects are planned upstream.

If you know you will require more than one 'project' for your product, team, project, etc.:

• Use a top-level 'project' as your default backlog. This keeps it easy to find and will give you a place to maintain a basic level of prioritization, eg 'Cool-Project'
• Use child 'projects' for iterations, components, etc., eg 'Cool-Project-Sprint-1' or 'Cool-Project-Some-Component'

There are different implementations of this principle. Check these examples and choose the way that works best for you (more real examples are welcome):

• A 'project' umbrella acts as default backlog, pushing some tasks to specialized subprojects: VisualEditor...
• A team 'project' acts as default backlog, pushing some tasks to specialized 'subprojects': Phabricator...
• A team 'project' acts as default backlog, pushing some tasks to regular sprints: Analytics-Engineering, Engineering-Community...

If/when your 'project' is complete, abandonded, etc., it should be archived.

Sprints

Some projects/teams organize their work around sprints (a.k.a iterations). Sprints are of a fixed duration, usually somewhere between one and three weeks. In Phabricator, each sprint requires the creation of a new 'project'.

The Sprint Burndown View provides a statistical overview of task activity, using the workboard as its primary source. It includes a burndown chart that is always current with activity on the workboard. It also adds pie chart visualization of the relationships between points, tasks, task status and workboard columns.

To enable a project as a Sprint, simply select the "Is Sprint" check box in the Project Edit Details page. After a project is enabled as a Sprint, you must then enter a start and end date to define the period scope. Then add some tasks to that project, and edit the tasks to set some story points. At sprint start, tasks from the prioritized backlog can be moved into the current Sprint. When your sprint is complete, it should be archived.

One approach in Phabricator is to have a "SomeProjectX-currentSprint" project as well as "SomeProjectX", and add the former project to those tasks in "SomeProjectX" which you plan to work on in that current sprint.

You can also view a list of all Sprint enabled projects by going to the Sprint application main interface at /project/sprint.

The Sprint functionality is provided by the Phabricator Sprint extension. For a more detailed description of the extension, check the Release Notes.

Archiving a project

When a 'project' or sprint is complete, abandoned, or otherwise no longer active, it should be archived. This prevents clutter and signals to others that the 'project' is inactive.

Assuming you have appropriate permissions, to archive a 'project':

1. Go to your 'project' page (e.g. https://phabricator.wikimedia.org/tag/project-management/
2. Click 'edit project'
3. Click 'archive project'

Boards

Play media

An introduction to Phabricator workboards

Boards are useful to follow the development status of tasks within a 'project'. Keep in mind that boards are not just a means of managing the flow of work. It's a communication tool both for your team/project/etc as well as to the public/stakeholders/etc. Boards should be used and maintained with this in mind; the simpler and clearer the language used, as well as the clarity of organization of your board, the better for communicating to a broader audience (see #Use plain language, define actions and expected results).

A 'project' can have a Board, such as phab:tag/mediawiki-core-team/board/. The default Board has a single column, "Backlog".

You can create arbitrary columns in this such as In development, Blocked with questions, Code review, Product review, and Done. Then much like other 'project' management tools you can drag and drop tasks to move and reorder them. When the board is created, a template board from a base 'project' can be imported for each new similar 'project'.

A 'project' can only have one Board, e.g. the Phabricator project itself has one Board. In comparison Mingle directly supports identifying tasks in the current sprint, and in Trello it's common to have separate boards for the current sprint and backlog, or even a separate board for each sprint.

The default Board filter is to only show open tasks, but you can change Filter to "All Tasks" to see Done tasks

Setting up a Workboard or Sprint Board

Different types of columns corresponding to different types of project, types of teams, purposes of the board...

Good examples that you can use to import your own board (you can also create your own columns, but check out these alternatives before):

• Backlog, Need Discussion, Ready To Go, Doing (links to examples)
• Backlog, Doing, Review, Done (https://phab08.wmflabs.org/project/sprint/board/15/query/all/)
• To Do, In Progress, In Review, Done
• Sprint X (X is different for each sprint board), In Development, Code Review, Product Review, Scrum-of-scrums interdependencies (https://phabricator.wikimedia.org/sprint/board/1050/)
• Please add more

Maintaining Boards

In principle, people assigned to tasks of a 'project' are the ones managing the board of such 'project', and especially the position of the tasks they are working on.

Formal teams might have formal meetings to update the board, and they might also have a product/project owner in charge of keeping the Board up to date.

Just a detail: if you need to drag a card to a position in a column that is out of reach, you can click the card to hold it and, without leaving the mouse, scroll up/down with the arrow keys or two fingers in your touchpad.

Frequent feature requests for boards include:

• Phabricator boards should live update
• Policy to define who can move cards in a workboard
• Restrict modification of tasks when they enter sprints
• Process to request a private project (and manage a private board)
• Ability to designate sub-workboards in Phabricator

Note: the current implementation of Boards does not automatically update with task status changes. Custom Board column to Status mapping may be possible in the future...