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, author (creator), assignee, description, projects/tags, 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'.

Task Types (aka "Subtypes")
Different types of tasks can have different fields that describe details which are unique to a given type. For example:


 * Release tasks have a release date.
 * Deadlines have a due date.
 * Log error reports can have an error id, URL and stack trace.

What determines the type of a task
The type of a task is initially determined by the form that was used to create the task. The type of a task can be changed manually by some users (via the "Add Action… → Change Subtype" dropdown) and also via automated edits when a task matches a specific Herald rule.

Generally users should not modify the type of a task unless there is a very specific reason for doing so. The maintenance of task types is best left to Phabricator administrators and experienced project managers.

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 completeable 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 is used for goals identified in the quarterly planning process of the Wikimedia Foundation. 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 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
Each Task may be assigned to one person. As with Priority, this is inherent to the Task, and affects every Project that Task is in. So it is impossible to have a Task assigned to Robin in one Project, but to Kim in another. The assigned person is displayed as part of the Task card in each Workboard.

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 project owner says what needs to get done, and the team itself figures out whom will work on what.

Some teams might choose to assign Tasks to people while the Tasks are in a TODO column. Others would have people assign Tasks to themselves only at the moment that they are moving them from TODO to DOING. Assigning a Task to yourself before you are ready to work on it is a form of cookie licking.

After the main work on a Task is finished, there are 2 main patterns for assignment:
 * The Task remains assigned to whoever did the work, as that task's permanent owner
 * The Task gets reassigned to whoever needs to work on it next

So for example, after code has been written, it might needs a code review from some specific person. In the second case, the Task would be assigned to that person, making it clear who is responsible for moving that task forward. Obviously if there are multiple possible code reviewers, that model would not work. Later, if the issue were waiting for someone to test it, or deploy it, or to run some specific task necessary for the Task to be completed (like a re-index), the Task could be assigned to that person. A team might have a policy that completed tasks should get assigned back to the person who originally created them, so that person can verify that their needs were met, and the task is ready to be closed.

Setting task priorities
Each Task has a Priority field, which is reflected in the sidebar color of Tasks that appear in Workboards. Note that this Priority is inherent to the Task, and thus will be the same in every Project and Workboard that task appears in.

One task can have only one set priority at a time. Priority should normally be set by product managers, maintainers, community liaisons, 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.

Within a Workboard, Tasks can be grouped by priority within a column. Choose "Natural" to have no grouping. Drag and drop Tasks up or down within a column. This allows a groomed backlog to be sequenced by priority, or could indicate the urgency of items in a "Needs Review" column. Note that Workboard columns can be grouped by several criteria, so while discussing a Workboard with someone not in the room, it is best to agree on and use the same sort order to avoid confusion.

Priority levels

 * See also Language portal/Task Priority, Wikimedia Security Team/Prioritization of bugs, 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 has not yet been determined. Note that some projects or teams do not use priority levels. In that case, Needs Triage usually equals Low or Lowest.
 * 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).

Tasks which have a deadline
You can create a task with a due date by using this form. You can add a due date by clicking edit task.

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

Since February 2016, Phabricator supports nested projects (subprojects, see below), so Projects do not have to be at the top level anymore. Naming conventions are used to communicate the intention of hierarchical relationships.

Types of Projects


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


 * Types you can directly create as a member of Project-Admins:
 * Component is the default option. A component corresponds to a distinct and recognizable piece of software, service, event or any set of periodically occurring tasks of the same type (ie. access or any other requests). If you are unsure, go for this. Icon+Color: Briefcase+Blue.
 * Umbrella Projects could 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. Icon+Color: Umbrella+Blue.
 * Group (formerly Team) corresponds to an existing team. If you belong to a group that will manage several projects, then create a Project for your group. Group Projects can be automatically added to (sub)component tasks by requesting a global Herald rule. Icon+Color: Group+Violet.
 * Goal can be used for Projects without a defined ending date but which can definitely realistically be defined as finished at some point. Icon+Color: Goal+Orange.
 * User (formerly Personal) Projects allow to track progress of personal tasks. They currently are a test only, see T555. Icon+Color: User+Checkered.
 * Types that must [ be proposed and discussed before being created]:
 * Tag is used as a cross-component keyword (like "accessibility"), a "never-ending" project. Icon+Color: Tag+Yellow
 * 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. See T90491. Icon+Color: Policy+Red.
 * Types deprecated by Milestones (there can still be valid reasons to have such "detached" top-level projects though, if milestones do not fulfill your needs):
 * Sprint is used for projects of a team being worked on in a certain time frame. Specify the start and end dates. Unless the extra flexibility (and subsequent manual maintenance) of a separate detached Sprint project is needed, it is recommended to create a Milestone of the sprint's parent project, instead of a separate detached Sprint project. Icon+Color: Timeline+Green.
 * Release is for planning a specific deployment of a project, defined by a date or a (future) software version. Unless the extra flexibility (and subsequent manual maintenance) of a separate detached Sprint project is needed, it is recommended to create a Milestone of the release's parent project, instead of a separate detached Release project. Icon+Color: Release+Orange.
 * Special cases (only listed for completeness):
 * The Patch-For-Review project is automatically added to a task when a related patch in Gerrit links to that task.
 * 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.

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

Parent Projects, Subprojects and Milestones
Phabricator provides Subprojects and Milestones as special cases of Projects. The upstream documentation provides great detail. To create a subproject or milestone, you must do so through its parent project. From the project that you want to become the parent, click on the subprojects icon in the left navbar. From there, you should see options to create a subproject or milestone. Converting an existing project to become a subproject or milestone requires shell access on the Phabricator server.

Feature comparison for projects, subprojects, milestones, and workboard columns
Here are some highlights:
 * Searching
 * Searching for a parent project also returns results from the subprojects.
 * Users and members
 * Membership in a project ("joining") is different from subscribing. Subscribing to a project is sufficient to get notifications, so actual membership might not be needed.
 * Subprojects, and projects that don't have subprojects, can have members.
 * Projects that are parents of subprojects cannot specify members. Instead, the members of all its subprojects are treated as being is members.
 * Milestones (which are NOT considered subprojects) cannot specify members. Instead, the members of its parent project are treated as being its members.
 * If a project has no subprojects, but then one is added, the existing Project becomes a “parent” Project and all of its members shift to that first Subproject.
 * Data Modelling
 * Subprojects can have their own Subprojects (up 16 subprojects deep).
 * Parent projects can have their own tasks.
 * Subprojects at the same level can share tasks.
 * Subprojects on different levels in different subproject hierarchies can share tasks.
 * Tasks in Milestones can only be in one Milestone.
 * Interface and workboards
 * Subprojects and Milestones have their own workboard.
 * Milestones exist as columns within the subproject's workboard.
 * Milestones will show up in the board of the associated subproject.

Converting projects into subprojects / milestones
To request conversion of one or more projects, please file a task and be sure to include these crucial details:
 * The name of the project which will become the parent project
 * The names of projects that should be converted
 * For each of the converted projects, describe whether it should be a subproject or a milestone.
 * If the converted project will become a milestone:
 * Milestones cannot have members, therefore, what should happen to the members of that project? There are two choices:
 * Either the members get added to the parent project, or
 * The list of members is discarded when the project becomes a milestone.

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

Projects are favored over 'tracking tasks' with dependencies.

Archiving a project
If/when your Project 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.

Make sure to handle the open tasks of your archived Project: Either associate the tasks with at least one other active Project, or close the tasks as declined in combination with an explanatory comment.

If your archived Project has been superseded by another Project, click Edit Details and edit the project description to say so in the first line. This allow others to find the newer Project.

It is 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 one single board. You can access it by clicking the Workboard icon in the left-side menu of the project. If there is no such icon, the board is disabled. You can enable it via "Manage" in the left-side menu and then choosing "Edit Menu" on the right.

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.

It is not possible to delete a column, however you can hide a column.

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

"Done"
Each Task has a Status field, which includes the state of Resolved. Resolved tasks are by default hidden from Workboards. When they are displayed, they appear grayed out and struck out. Other statuses include Open and Stalled.

Note that this Resolved status is inherent to the Task, and so will affect that Task's appearance and behavior in every Project (and Workboard) it is in. This is independent of which column a Task might be in, in any given Workboard. So a Task could be Open, and could be in the DONE column of one Workboard, but the DOING column of another. It could also be in the  column somewhere else.

As a result, it is important not to mark a task Resolved until it is considered done by ALL of the projects it is in. It's fine to move a Task to your own Workboard's DONE column, but before you mark a task Resolved, ensure that no other project still wants to keep tracking its progress.

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 seems to work well in Chrome on Linux but 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 Project Management 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.

Legend for diagrams
Different colors represent different categories, compoments, or subprojects of a master project. For example, "Database", "UI", "Reporting". Each "category" may be a distinct Phabricator project, or a column within a project, or may just be a conceptual category that is tracked manually and through task titles. A white box with shaded black border represents the default column for new tasks, typically "To Triage". In these examples, the colored bars represent lists of tasks, not single tasks of varying size. Different shades of the same color represent tasks in progressive changes of status, such as "In design", "In development", "In Testing". Tasks are often grouped by priority within each column, with the most important to the top.

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.
 * Note that new tasks (including existing tasks that somebody else tags with this project) will mix with the existing list of tasks. A separate default column would make this clearer.

Columns show status
A team uses its Team Project Workboard to track workflow. Each column on the board reflects a different, progressive status. Tasks move through columns like INBOX, IN PROGRESS, IN REVIEW, and DONE. Tasks added to the board default to a "To Triage" column at the left side. Tasks are not systemically differentiated into categories, though tasks' other projects are visible as tags within the task boxes. Example: Analytics-Kanban. See below for more information on Kanban in Phabricator.



Columns show categories
A team uses its Team Project Workboard to track workflow. Each column on the board reflects a different category of work within the overall project. Tasks are moved to columns to indicate which category they belong to. Task status is effectively binary, where open tasks are visible and resolved tasks are hidden. Tasks do not usually change columns. Tasks added to the board default to a "To Triage" column at the left side. Example: VisualEditor.



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.

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

One project board and one status board
A team may use one board to track all tasks, with different columns showing different categories, and then use a second board to track status of work in progress. The tasks may belong to both boards, or to just one board.



One project board and one board per iteration.
A team may use one board to track all tasks, and then track status in a separate board, using a different status board for each iteration. This is the most common configuration for Scrum (see the section below for more details).

A team Project acts as default backlog, pushing some tasks to regular sprints: Analytics-Engineering, Engineering-Community. In this mockup, tasks from different categories are all in one long Backlog column on the main board, in priority order by individual task.



A team Project could also use different columns to track different categories, and sprint boards to track status:



One project board, different tags for components, and a status board.
A team may use one board to track all tasks, with additional tags to track each category, and then track status in a separate board. In this diagram, the Project board shows all tasks from all categories in a single unified backlog column.



If the categories are often used by other people outside the context of the team board, an admin can create a global Herald rule so that tasks added directly to the subproject boards are automatically added to the parent board.

Other Designs

 * A team Project acts as default backlog, pushing some tasks to specialized categories: Phabricator...

Other considerations
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'. This project should have a "To Triage" or other column as default that makes it clear when new tasks are added but have not yet been reviewed.
 * Use naming to group iterations, components, etc., eg 'Cool-Project-Sprint-1' or 'Cool-Project-Some-Component'
 * Consider the pros and cons of using subprojects 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.

Kanban in Phabricator
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 in Phabricator
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 the integrated the integrated charts, Phlogiston, Phragile.

A sprint project could be a subproject, 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