Phabricator/Project management
You have a project in Phabricator that you maintain or manage. 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?
Engineering teams in the Wikimedia movement 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 tasks can 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 to sync different tools and keeps the visibility of bugs/issues high by not spreading teams' focus across multiple tools.
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.
Task Types
See Phabricator/Help/Forms#Task Types (aka "Subtypes")
Scope of tasks
The basics: Phabricator/Help#Creating a task.
Tasks need to describe an achievable objective. It must be possible to define a task as finished at some point. 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.
- To create a subtask, see Phabricator/Help#Creating a task.
- Trivial subtasks that one person can complete in a moment but should be documented can be just added as a checklist (via
[ ] itemmarkup; see Formatting and markup) 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 project tag. (For completeness: There are also a release tag for identifying software releases, or goal, story, spike tags. See phab:T93499 for some history.) As of 2020, this older concept (using project tags to define task scope) overlaps with using task subtypes (a functionality which was made available lately).
Use plain language, define actions and expected results
Tasks are the primary building block of Phabricator and 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 https://en.wikipedia.org/wiki/XYZ 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 and anybody can try to reproduce. The latter may only make sense to a software engineer who is intimately familiar with Special:Random. Define tasks in simple language and in a way that can be understood by a broad audience.
Associating tasks with projects
A task in Phabricator can be associated with multiple project tags.
If applicable, please add codebase project tags and not only team project tags to code development tasks. Teams can get disbanded or team responsibilities shift while a codebase usually remains.
Tasks do not only cover teams' plans but should also allow contributions from outside of teams. Furthermore, this allows communicating that a team does not plan to work on a task by removing the team project tag while keeping the codebase project tag.
Example: A task has a codebase project tag (so everyone can find tasks related to the codebase) and an engineering team tag (so the team has the task on their team workboard for their planning).
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 that use project workboard columns 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. Do not assign a Task to yourself if you are not realistically close to working on it (doing so is called "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 (e.g. QA or PM sign-off)
So for example, after code has been written, it might need 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 set to "resolved" status.
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, counteractions might be taken as outlined in the etiquette.
Within a Workboard, Tasks by default are grouped by priority within a column. In the upper right corner, you can change the grouping or sorting. 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.
Every task has a Priority field which offers the levels listed below.
Using the Priority field is one concept which allows developers or managers to plan work. Some projects or teams do not use the Priority field for their planning.
Apart from the levels "Unbreak Now!" and "High", there are no shared norms across teams and developers how priority levels should be interpreted and used. Understanding varies widely across projects and teams.
- Needs Triage – Default option. The task priority has either not yet been determined, or the Priority field is not used by the project or corresponding team. In the latter case, Needs Triage usually means low priority.
- Unbreak Now! – Something is broken and needs to be fixed immediately, setting anything else aside. This should meet the requirements for issues that hold the train.
- High – Someone is working or planning to work on this task soon.
- Medium – In some projects, this means that someone is planning to work on this task in some foreseeable future. In some projects, this means the same as Low.
- Low – The task is not on anybody's to-do list. The task is not considered urgent. We would be happy if someone volunteers to work on this task.
When projects and teams use the Priority field, then usually the tricky part is to handle High–Medium–Low in a consistent way, especially for tasks that are still unassigned. One way to approach this for development teams:
- High priority for tasks committed for the current sprint, or that need to find an owner who can start working on them soon.
- Medium 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.
Tasks that cannot be worked on yet
Certain tasks might not be actionable until an action has been performed outside of the task itself. A task is not stalled just because nobody is currently working on the task.
- If a task depends on another task in Phabricator, you should set the number of that other task under "Edit Related Tasks... > Edit Subtasks" (see also Phabricator/Help#Parent tasks and subtasks). Afterwards, the other (sub)task will be displayed under "Task Graph".
- If a task depends on further information from a third party, you can explicitly set the status to "stalled" (see also Bug management/Bug report life cycle). In addition:
- If a task needs information from the task author, always include instructions which information is needed.
- If a task depends on an upstream project or developer, also associate the "upstream" project tag.
- If a task needs retesting, also associate the "testme" project tag.
Tasks that have a deadline
You can create a task with a due date by using this form. You can add or remove a due date by clicking "Edit task".
Normally, you should only add a deadline for event-related tasks (tasks that would be pointless to do after the deadline) or for work you are doing yourself.
Closing a task
A task can be closed as Resolved, Declined, or Invalid by changing the task status. A task can also be merged as a duplicate of another task via "Edit Related Tasks... > Close As Duplicate". See the bug report life cycle for details.
The task status should be set to "Invalid" if a task fails defining an actionable objective (e.g. never-ending tasks, support questions, generic complaints...) Users resolving a task as Invalid should explain their reasons in a comment (also see the Bug report life cycle). Tasks can always be reopened.
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 an engineering team within a Wikimedia organization. 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 project 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, counteractions might be taken as outlined in the etiquette.
Creating custom forms for Task Creation and Editing
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.
- 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.
- 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 task T128161. Icon+color: Meta (gears)+Grey.
The icons and colors associated with different types of Projects are a convention, not enforced by software.
Creating and renaming projects
The basics: Phabricator/Creating and renaming projects.
Do not create neverending 'tracking tasks' which will always remain in "open" status and have subtasks as dependencies. That is exactly what project tags are for.
Archiving a project
If/when your Project is complete, abandoned, or otherwise no longer active, it should be archived. This signals to others that the Project is inactive, prevents clutter (it is not listed anymore in the autocomplete proposals of the "Project Tags" field), and (after checking your project's open tasks) reduces the risk that open unassigned tasks drop off the radar and will be forgotten.
To archive a Project:
- go to your Project page (e.g. https://phabricator.wikimedia.org/tag/phabricator/);
- click the Manage item in the navigation bar on the left;
- 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. It is possible to edit multiple tasks at once.
If your archived Project has been superseded by another Project, click Manage and then 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.
Parent Projects, Subprojects and Milestones
Phabricator provides Subprojects and Milestones as special cases of Projects. The upstream documentation provides great detail.
Creating (sub)projects and milestones requires being a member of Project-Admins. Please follow Phabricator/Creating and renaming projects if you think that you regularly need such permissions.
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.
| Type of Project | Query | Create or Update | Read | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Search for | Included when searching for parent | Edit via field edit | Edit via drag and drop on board | Can have Sub-Project child. | Can have Milestone child. | Edit in API | Appears as a column on Parent board | Can be ordered on
Parent board |
See tag on task row in search results | See on tag on card on board | See in detail page | ||
| Project ("Foo") | Yes | No | Yes | No | Yes | Yes | Yes | No | No | Yes, as Foo | Yes, as Foo | Yes, as Foo | |
| Sub-Project ("Bar") | Yes | Yes | Yes | No | Yes | Yes | Yes | No[1] | No | Yes, as Bar | Yes, as Bar | Yes, as Bar | |
| Milestone ("Baz") | Yes | Yes | Yes | Yes | No | No | Yes | Yes | Yes[2] | Yes, as Foo (Baz) | Yes, as Foo (Baz) | Yes, as Foo (Baz) | |
| Project Column ("Qux") | No | Yes | Yes[3] | Yes | No | No | Yes[4] | Yes | Yes | No | No | Yes, as Foo (Qux) | |
References
- ↑ https://secure.phabricator.com/T11036
- ↑ phab:phame/post/view/196/moving_milestones/
- ↑ via the "Add Action… → Move on Workboard" dropdown
- ↑ https://secure.phabricator.com/T12074
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 watching a project. Watching 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.
Here are some warnings, to avoid wrong expectations:
- Tasks in subprojects will not show up on the workboard of the parent project.
- Tasks in a milestone cannot be in another milestone of the same parent project, or in another column on the parent project workboard than the milestone column.
- When all subprojects of a parent project are archived, to become a member of the parent project, one still has to join an (archived) subproject. According to upstream in https://secure.phabricator.com/T12887 this is not considered a bug.
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.
- Milestones cannot have members, therefore, what should happen to the members of that project? There are two choices:
Members and watchers
Phabricator users can add themselves as a member and/or watcher to most projects. For most projects, being a member does not have any effect, although it does add it to the list of "projects" located on your user page. Being a watcher will cause you to receive an email anytime that any ticket within the project receives a comment or activity.
Boards
The workboard is one user interface for viewing and manipulating tasks that belong to a project, in addition to lists of tasks. Project tags which are not used for actually planning work 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 #Use plain language, define actions and expected results).
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.
You can access the board of a project by clicking the Workboard icon in the left-side menu of the project. If there is no such icon, the board is disabled. If there are good reasons to have a workboard, you can enable it via "Manage" in the left-side menu and then choosing "Edit Menu" on the right. 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.
Filtering content on a board
The default board filter shows only "Open Tasks". You can change the filter to "All Tasks" or "Assigned to Me", or to a custom search (e.g. on date ranges, or to only display some task subtypes, or to only display tasks which also have another project tag set).
Columns
Project boards may display the tasks in the project in multiple 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 - see the examples below.
Within a Workboard, Tasks by default are grouped by priority within a column. The order of tasks within each column and each group is maintained. 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.
Moving tasks between columns
Much like other 'project' management tools you can drag and drop tasks within and between columns to recategorize them. There are 2 ways to move a task from one workboard column to another:
- 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 the dropdown above the field to add a new comment.
Boards automatically update with task changes, so if you are viewing a workboard while other people are editing or moving tasks, refreshing via the web browser to see the updates should not be needed.
Automated actions via column triggers
Automated actions, for example board column to task status mapping, are possible via triggers when a task is dragged and dropped from one to another workboard column. Triggers can add or remove project tags, set a task assignee, or change task priority or task status. Triggers are not executed when moving a task on the workboard via other means than drag and drop.[1]
You can configure workboard column triggers by pressing the cogs icon in the column header.
For automated actions not related to moving a task to another column on a workboard (for example automatically adding project tag X when a task is created with project tag Y), use Herald.
Story points per column
This section is only relevant if your engineering team uses the "Estimated Story Points" field that each task has.
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.
Estimated VS Final Story points
If "Estimated Story Points" is not enough and you would also like to set a "Final Story Points", for example to declare how many hours you estimated, and how many hours you really invested; you may notice that "Final Story Points" is not a field that is generally shown.
To activate this additional field "Final Story Points" you can change the "Subtype" of the task and set "Bug report" (or anything more specific than just "Task").
To show this additional field you can also just set the Deadline date. This will escalate the Subtype from Task to Deadline, getting the same results.
Note: final story points are not shown on columns generally, to do not clog the user interface.
Hiding and deleting columns
It is not possible to delete a column, however you can hide a column via the dropdown in the column header.
You can display hidden columns or change the order of columns by going to the workboard, selecting the cog icon ("Manage") in the upper right corner, and then choosing "Reorder Columns".
Typical examples for uses of workboards
- Workflow / Progress
- Typical columns track the state of tasks, such as TODO, DOING, DONE. See the examples below.
- This supports both Scrum-style sprint iterations (see #Scrum in Phabricator), and Kanban-style continuous work (see #Kanban in Phabricator).
- Tasks are moved from column to column regularly as work progresses. The task status remains open until they reach a terminal column, after which the task status should be changed to resolved if the global task status does not collide with another associated project tag. See #"Done" column versus "Resolved" task status.
- Planning
- These boards divide tasks into temporal or sequential categories.
- Each column might represent a target release (version 2, though this could also be a milestone), or general timeframe (e.g. 2022 or FY2021-22). Avoid ambiguity and be clear!
- 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
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
- 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
- Backlog, Needs plan, Needs Code, Non-Code, Non-core-API stuff, In Dev, Needs Review (Example: MediaWiki-API; T90003)
- 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.
"Done" column versus "Resolved" task status
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.
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; }}
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 the historical document 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 by default grouped by priority within each column, with the most important to the top.
Single Board
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.
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 in combination with Analytics-Kanban. 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, a global Herald rule can add tasks which were added directly to the subproject boards also automatically to the parent board.
Other Designs
- A Group (team) Project acts as default backlog, pushing some tasks to specialized categories.
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 #Parent Projects, Subprojects and Milestones 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 via "Edit column > Point Limit" in the column header dropdown. 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 w:Cumulative flow diagrams showing cycle time and lead time. Experimental work was done on this by Phlogiston (see phab:T253964).
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. Other past approaches were Phlogiston (see phab:T253964) and Phragile (see phab:T240308).
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 should archive the sprint project. 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 should typically be archived (so would no longer be visible).
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.