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.

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

When T1322 is deployed: 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.
 * 2) Click 'edit project'
 * 3) Click 'archive project'

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.

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 add explain their reasons in a comment. 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 picked up by whoever is going to 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 who will work on what.

You can assign a task to yourself if you have some plan to work on it in the short term (say a few weeks, a couple of months, the upcoming sprint...). There is no use in having tasks assigned that haven't been touched for a long time. See also: cookie licking.

Setting priorities
One task can have only one priority at a time. This limitation leads to the art and science of prioritizing tasks keeping multiple perspectives in sync: project level, sprint level, team level, individual level...

Priority should normally be set by product managers, maintainers or developers who plan to work on the bug, 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.

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
The first perspective that must be sensible is the personal perspective. If the priorities at a personal level are not accurate or realistic, the other views aggregating personal priorities will be directly affected.

The "Assigned to Me" task view needs to be always realistic. For instance, having 17 high priority tasks assigned to one person is not realistic. Defaulting to three high priority tasks makes a lot more sense, committing to five or so in exceptional times. More than this it is probably not realistic, or not sustainable.

Associating tasks to 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.

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