Phabricator/Project management

You have a project in Phabricator that you maintain or manage. Now what? There are many possible ways to run a 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.

Phabricator is an open source project primarily written in PHP. Patches to Phabricator are welcome after discussion. :)

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.

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. Also consider this piece of advice: does your task require more than a couple of hours of work? Then you may want to Phab it. Would there be nasty consequences if you forgot executing that task? Avoid this by Phabbing it.

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

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 in doubt, do not change the Priority field value, but add a comment suggesting the change and convincing reasons for it.

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

 * See also Language portal/Task Priority and other Wikimedia Foundation teams internals.

Wikimedia Phabricator offers these priority levels to allow developers to plan their work: 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 for development teams:
 * 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 someone is still planning to work on it.
 * Low - Less priority than Normal, but someone is still planning to work on it. This does not necessarily mean the task is not important; it is just not on the to-do list of anybody as the task is not considered urgent.
 * Lowest - Nobody plans to work on this task, but we 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 that 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.

Creating custom forms for Task Creation and Editing
Phabricator allows adminstrators to create custom forms for task creation and editing. Phacility has some documentation on this.

Some likely use cases include:
 * Custom markup at the top of forms
 * Pre-filling information in fields
 * Hiding certain fields
 * Bug reporting and template tasks can be entered more easily

A great deal of caution is required when using this new functionality. Form creation is limited to admins because it is currently too easy to accidentally override existing forms when someone creates a new form without fully understanding the subtleties of the new system. Anyone with a use-case for a custom form can request that one be set up by Phabricator admin. We have not established a formal process for this yet.

Projects
Projects are the basic organizational method in Phabricator; they are a way to organize tasks and manage workflow or to "tag" for queries and general organization.

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.

Phabricator only recently (February 2016) started to support nested projects (sub-projects, see below), so all Projects are currently at the top level. Naming conventions are used to communicate the intention of hierarchical relationships.

Types of Projects


There are several types of Projects in Wikimedia Phabricator, and each type must follow the purpose, color, and icon defined in these guidelines.


 * Component is the default option. A component corresponds to a distinct and recognizable piece of software/service. Creation must be documented. Icon+Color: Briefcase+Blue.
 * Team corresponds to an existing team. If you belong to a team that will manage several projects, then the first step is to create a Project for your team. Creation must be documented. Team Projects can be automatically added to (sub)component tasks by requesting a global Herald rule. Icon+Color: Team+Violet.
 * Sprint is for sub-projects of a team being worked on in a certain time frame. Specify the start and end dates when requesting creation of a new Sprint Project. Icon+Color: Timeline+Green.
 * Release is for sub-projects that belong to a specific deployment defined by a date or a (future) software version. Icon+Color: Release+Orange. See below
 * Goal can be used for Projects without a defined ending date but which can be definitely realistically be defined as finished at some point. Creation must be documented. Icon+Color: Goal+Orange.
 * Tag is used as a cross-component keyword (like "accessibility"), a "never-ending" project. Tags must [ be proposed and discussed before being created]. Icon+Color: Tag+Yellow
 * Meta projects are used to tag code repositories with special behaviors and workflows. These behaviors are triggered by custom Herald rules. See . Icon+color: Tag+Grey.
 * ACL projects are used to enforce policy restrictions, especially for Spaces. This type should be used instead of locking down normal projects such as Teams, so that anyone may still join and watch such Team projects without that giving them restricted access. Creation of such a project or a related Space must [ be proposed and discussed before being created]. See T90491. Icon+Color: Policy+Red.
 * Personal per-user Projects allow to track progress of personal tasks. They currently are a test only, see T555. Creation must be documented. Icon+Color: Accounting+Checkered.
 * Umbrella Projects can be used for larger Projects that do not have a distinct code base and that consist of several (sub)components. Umbrella Projects can be automatically added to (sub)component tasks by requesting a global Herald rule. Creation must be documented. Icon+Color: Umbrella+Blue.
 * The special Patch-For-Review project is automatically added to a task when a related patch in Gerrit links to that task.

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

Parent Projects, Sub-projects and Milestone
The upstream documentation provides great detail.

Here are some highlights:
 * If a Sub-project is added to an existing Project, the existing Project becomes a “parent” Project and all members shifts to the first Sub-project.
 * Parent-projects' members (the users who have joined the project) are the union of all Sub-projects' members. When adding the first Sub-project to a parent, all existing members get moved to the Sub-project.
 * Sub-projects can have their own Sub-projects (up 16 sub-projects deep).
 * Milestones exist as columns within the sub-project's workboard.
 * Sub-projects and Milestones have their own workboard.
 * Parent projects can have their own tasks
 * Sub-projects at the same level can share tasks
 * Sub-projects on different levels in different sub-project hierarchies can share tasks
 * Tasks in Milestones can only be in one Milestone
 * Milestones will show up in the board of the associated subproject.

Creating/renaming projects
The basics: Phabricator/Creating and renaming projects.

Projects are favored over 'tracking tasks' with dependencies.

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...
 * If wanted, an admin can create a global Herald rule so that the umbrella Project is automatically added to all tasks in the corresponding subprojects.
 * 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, abandoned, etc., it should be archived.

Kanban
Kanban is a lean development approach. It focuses on limiting Work In Progress (work started but not done) and reducing "batch size" so more work gets accomplished faster.

Phabricator's workboards can facilitate some parts of Kanban. Set up a column for each state of Work In Progress, leading to a Done column. You can limit tasks in each column in workboard view > Edit column > Point Limit. If you're not using story points, then don't make the project "Is sprint".

Phabricator and its Sprint extension doesn't yet support Kanban's Cumulative flow diagrams showing cycle time and lead time.

Examples
The Analytics Engineering team has an Analytics-Kanban workboard with limits on the number of tasks in some columns. The Analytics-Backlog board feeds into this.

Sprints
Some projects/teams organize their work around sprints (also known as iterations). Sprints are of a fixed duration, usually somewhere between one and three weeks. In Phabricator, a sprint is a Project with some additional features.

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, follow any link to an existing Project and click Edit Details, then check the "Is Sprint" box in the Edit Project page and [Save]. Then you must edit the Project again to enter a start and end date to define the period scope for burndown planning (otherwise there are errors, T91516). We usually name sprints "ProjectOrTeam Name-Sprint StartDateOrNumber" At the start of a sprint, add tasks from your prioritized backlog(s) to the current sprint by adding the sprint's tag to each task's Projects field. You can also enter a numeric estimate of the amount of work the task represents in its Story Points field. (This is standard Agile software development practice.) When your sprint is complete, you can archive it. If you did not complete a task, add the next sprint's tag to its Projects field.

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 /project/sprint.

The Sprint functionality is provided by the Phabricator Sprint extension. For a more detailed description of the extension, check its 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/phabricator/);
 * 2) click the Manage item in the navigation bar on the left;
 * 3) click Archive Project.

Note it's not possible to delete a Project in Phabricator.

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

Every 'project' has a single board, such as tag/mediawiki-core-team/. You can access it by clicking the Workboard icon in the left-side menu of the project. When you first set up the board for a project, you can choose "New Empty Board" which starts with a single "Backlog" column; or you can choose "Import board columns from another project" to use another board's set of columns as a starting point. Thereafter you can create arbitrary columns in the board 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 within and between columns to reorder them.

In Phabricator a project can only have one board, but a task can be in multiple projects each with its own 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 only shows "Open Tasks", but you can change Filter to "All Tasks" or "Assigned to Me", or a custom filter.

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

Workboard/sprint board columns
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 (Test instance)
 * 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 (Collaboration-Team)
 * Backlog, Needs plan, Needs Code, Non-Code, Non-core-API stuff, In Dev, Needs Review (MediaWiki-API; T90003)
 * Please add more

Tips for forcing multiple columns to fit in the window
If the workboard has many columns, it might not all fit in your screen. This makes dragging tasks between columns more difficult (although you can use your keyboard's arrow-keys to scroll sideways), and seeing all the columns at once impossible. Here are two ways to override the default display

Using Stylish/userstyles.org in any browser.

Using Greasemonkey in Firefox: GM_addStyle(".aphront-multi-column-fixed .phui-workpanel-view, .phui-workpanel-view .phui-header-shell { width: auto; }");

Using Firefox's userContent.css (browser restart required): @-moz-document domain(phabricator.wikimedia.org) {.aphront-multi-column-fixed .phui-workpanel-view, .phui-workpanel-view .phui-header-shell { width: auto !important; }}

Try using your PageUp/PageDn keys while dragging a task. (This works nicely for me in Chrome on Linux just not in Firefox(Iceweasel)).

"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 general workboard types:

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

Examples from teams that actively use Phabricator workboards for project management

 * Discovery
 * Research and Data
 * Reading Web

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.

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