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 add it to Phabricator. Would there be nasty consequences if you forgot executing that task? Avoid this by adding it to Phabricator.

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 an 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 Related Tasks... > Edit Subtasks". Afterwards, the other (sub)task will be displayed under "Task Graph".

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
A task can be closed as Resolved, Declined, or Invalid. It can also be merged as a duplicate of another task (details). When a task is associated with multiple projects, care should be taken to coordinate the closing of a task with any relevant stakeholders. Anyone marking a task as declined or invalid should include a comment explaining why.

Many (but not all) tasks relate to projects that have specific "owners", such as a volunteer maintainer, or a team within the foundation. That owner would most often be responsible for updating the status of tasks within their project, and they might rely on a specific workflow. For example, marking a task "resolved" might mean that a patch has been merged, or that the product owner has verified the fix, or that the change has been deployed to production. The owner would also typically be in the best position to determine that the task should (or should not) be marked as declined or invalid.

In some cases, it would be appropriate for the task's status to be updated by someone other than the task's owner, such as the task author, a phabricator administrator, or an observer. But generally the owner of a task, if there is one, should have the final say on its status. For tasks that don't have a clear owner, the task author should generally be consulted about potentially controversial status changes.

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 Phabricator administrators to create custom forms for task creation and editing. Upstream documentation is available and a custom form just to demonstrate the possibilities is available.

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 administrators 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 administrators. 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.
 * Group (formerly Team) corresponds to an existing team. If you belong to a group that will manage several projects, then the first step is to create a Project for your group. Creation must be documented. Group Projects can be automatically added to (sub)component tasks by requesting a global Herald rule. Icon+Color: Group+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: Meta (gears)+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 Milestones
Phabricator provides Sub-projects and Milestones as special cases of Projects. See this comparison. The upstream documentation provides great detail. To create a sub-project or milestone, you must do so through its parent project. From the project that you want to become the parent, click on the sub-projects icon in the left navbar. From there, you should see options to create a sub-project or milestone. Converting an existing project to become a sub-project or milestone is not supported.

Here are some highlights: Note this potentially important but non-obvious consequence of the membership rules: Parent projects can't specify members, and milestones can't specify members. So a milestone's parent must itself be a sub-project, in order for that sub-project's members to be inherited by the milestone (and by the parent). However, also note that subscribing to a project is sufficient to get notifications, so actual membership might not be needed.
 * Searching
 * Searching for a parent project also returns results from the subprojects.
 * Users and permissions
 * If a Sub-project is added to an existing Project, the existing Project becomes a “parent” Project and all members (the users who have joined the project) shift to the first Sub-project.
 * Parent-projects' members 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.
 * Milestones themselves do not have members, however members of the parent project are members of the milestone.
 * Data Modelling
 * Sub-projects can have their own Sub-projects (up 16 sub-projects deep).
 * 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
 * Interface
 * Sub-projects and Milestones have their own workboard.
 * Milestones exist as columns within the sub-project's workboard.
 * Milestones will show up in the board of the associated subproject.

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

Projects are favored over 'tracking tasks' with dependencies.

If/when your Project is complete, abandoned, etc., 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/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
The workboard is the primary user interface for viewing and manipulating tasks that belong to a project. Projects which are used solely as supplemental "flags", for example i18n, may not use their 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.

Columns
Project boards may display the tasks in the project in multiple columns. A project that is itself used as a tag (i18n, Need-volunteer) may not use its board and thus will not have columns.

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 recategorize them. The order of tasks within each column is maintained, and you can drag and drop tasks up and down, so it is common to treat this as another kind of prioritization or stack ranking. A task can belong to only one column within each board.

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.

Each column has two numbers at the top, number of cards, and current "story point" count. If the column has a story point restriction (i.e. "this column should have a maximum of 20 story points between all tasks") then it will show the second number as a fraction (current over maximum). When the points exceed the limit, the numbers turn red.

Typical uses of workboards

 * Workflow
 * Typical columns track the state of tasks, such as TODO, DOING, DONE
 * This supports both Scrum-style sprint iterations, and Kanban-style continuous work
 * An example is Dumps-Rewrite, with Tracking, Up Next, active, etc.
 * Usually the Phabricator built-in states are integrated with the columns in that all tasks are kept open until they reach a terminal column, after which they are resolved.
 * Tasks are moved from column to column regularly as work progresses.
 * Planning
 * These boards divide tasks into temporal or sequential categories.
 * Each column might represent a target release (version 2), or general timeframe (e.g. 2016).
 * Tasks generally don't change columns other than in re-planning. Thus they will change from open to resolved without moving columns.
 * Categories
 * Columns might group Tasks by component, functional area, or even complexity
 * An example of sub-categorization is Mobile, which has as columns Needs triage, Not MobileFrontend specific, and MobileFrontend Specific. Note that this blends a little bit of state with the categorization, which is very common.

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

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.

There are 2 ways to move a task from one workboard column to another: The current implementation of Boards does not automatically update with task status changes, so if you are viewing a workboard while other people are editing or moving tasks, you will have to user the refresh feature of the browser to see the updates.
 * While viewing the workboard, drag the task and drop it in the destination column at a specific vertical position
 * NOTE: 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.
 * While viewing a task, choose the "Move on Workboard" action in a dropdown near the bottom

Custom Board column to Status mapping may be possible in the future...

Implementing Common Practices in Phabricator
Phabricator can support all of the common development practices used with Wikimedia, with varying degrees of completeness. See also Wikimedia Use Cases for Phabricator.

Simple List
The simplest way to use Phabricator to manage a project is as a to-do list.
 * Keep all tasks in one Project
 * Use the default column in the project to maintain a ranked list
 * Work from the top of the list.

Single Board with state
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.

Multiple Boards
Many teams and many products require more than one Project in order to efficiently organize their activity, because a workflow-oriented board is not well-suited for tracking and organizing future tasks and planning over a longer term. 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.

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 naming to group iterations, components, etc., eg 'Cool-Project-Sprint-1' or 'Cool-Project-Some-Component'
 * Consider the pros and cons of using sub-projects and milestones. These features are in flux in Phabricator and there are currently (May 2016) no recommendations for how best to use them. Refer to  to understand pros and cons.

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

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 set a story point limit for each column in workboard view > Edit column > Point Limit. Note that it is not a hard limit--there will just be a visual indicator at the top of the column if the sum of story points of open tasks exceeds the limit.

Phabricator doesn't yet support Kanban's Cumulative flow diagrams showing cycle time and lead time. Experimental work is being done on this by Phlogiston.

Multiple boards in 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
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.

Scrum
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. Before early 2016, support for sprints was handled by the Sprint Extension. However, Phabricator now natively allows tasks to have estimates.

You can optionally enter a numeric estimate of the amount of work a task represents in its Story Points field. ("Story points" is a common Agile software development term for an estimate.) For burndown or burnup charts, consider Phragile or Phlogiston.

A sprint project could be a sub-project, a normal project, or a milestone. Milestones are relatively new, so they aren't used much yet. However, it is expected that most sprints would eventually be milestone projects.

Sprints are typically named "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. 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.

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, most of the tasks in that sprint 's Workboard should be in the DONE column. Teams may change task state from open to resolved as tasks are moved to the DONE column or all at once at the end. 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.

Examples from teams that actively use Phabricator workboards for project management

 * Discovery
 * Research and Data
 * Reading Web