Phabricator/Project management

''Good practices for Phabricator project management. Coming soon. See T558''

You have a new project. 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 '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'.

This article will use single quotes around the word 'task' to differentiate the concept of a 'task' in Phabricator from standard uses of the word (e.g. "The teacher took him to task for being disruptive in class" or "cleaning the toilets turned out to be a difficult and disgusting task").

Scope of tasks
The basics: Phabricator/Help.

'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'.

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.

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 only assign a 'task' to yourself 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: 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:
 * 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.
 * 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.

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'.

To enable a 'Project' as a Sprint, add the special character '§' to the title of the 'project'. This enables the special functionality of a Sprint 'project', currently including a Burndown chart and a Sprint Board (more on workboards below). A Sprint 'project' is defined by a Start and End date, accessed in the detail view of the 'project', after the 'project' has been created. Also, every 'task' assigned to the Sprint can include Story Points.

Frequently teams have a long backlog of 'tasks', from which they pick the 'tasks' that they aim to complete in the next sprint. The recommended workflow is to create a base Sprint 'project' with all backlog 'tasks'. At the Sprint planning meeting, the prioritized backlog 'tasks' can be assigned point values, and at Sprint start, these 'tasks' can be moved into the current Sprint.

One approach in Phabricator is to have a MyProject-§currentSprint 'project' as well as §MyProj, and add the former project to the 'tasks' you plan to work on in the current sprint

When your sprint is complete, it should be archived.

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
Boards are useful to follow the development status of 'tasks' within a 'project'.

A 'project' can have a Board, such as 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/sprint/board/15/query/all/)
 * 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.

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)

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...