Not a lot has changed for Wikimedia's instance of Phabricator over the past few months. That's because a lot has been happening behind the scenes, as well as upstream at Phacility. Members of the Release-Engineering-Team and Team-Practices group have been working since December 2015 to integrate various upstream changes, however, nothing was released to our production instance because there were so many important features that were in-progress and not yet fully usable. Additionally, we had to figure out exactly how these features would fit with the specific needs of our project and test a lot of functionality to be sure that we would not break anyone's workflows.

So our Phabricator instance has been relatively unchanged since November of last year. This all changed last Wednesday night (Thursday February 18th, 01:00 UTC) when we unleashed several months of changes into production. If you use phabricator.wikimedia.org regularly then you have probably already noticed some of the more obvious improvements.

A whole lot of hard work went into this release. Thankfully, everyone's hard work seems to have paid off as we only encountered a couple of relatively small issues which were fixed quickly after.

This post is to fill everyone in about what's changed and what you can expect from some of the exciting new functionality that has been added with this release.

Custom Forms

• Some likely use cases include:
  • Custom markup at the top of forms (T115017)
  • Pre-filling information in fields
  • Hiding certain fields (T120903)
  • Bug reporting and template tasks can be entered more easily (T91538)
• A great deal of caution is required when using this new functionality.
  • Form creation is limited to admins because it is currently too easy to accidentally override existing forms when someone creates a new form without fully understanding the subtleties of the new system
  • @mmodell can answer questions about what is possible.
  • Anyone with a use-case for a custom form can request that one be set up by Phabircator admin. We have not established a formal process for this yet.

Customizable Project Pages

It's now possible to customize individual project pages to meet the needs of each type of project or the needs of specific teams.

• Custom links can be added to the navigation menu. This is great for prominently linking to a project wiki page or other relevant URLs that are relevant to a project.
• The default page that is shown when visiting a project can be configured. For some projects, it makes more sense to go directly to the workboard, for others, the project details page is more appropriate.
• We can disable the workboard entirely for certain projects (useful for 'tag' type projects)
• There is an API for developing custom panels to be placed on project pages or as part of the navigation menus. These are new and unstable but it is seems like a promising way for us to extend Phabricator with new functionality in the future.

Milestones & Sub-Projects

Projects can now be nested. There are two new types of projects in Phabricator and they could prove to be really useful for organizing all of the things. Sub-projects are just like regular projects, but nested inside of an existing project. Milestones are a special type of sub-project that can be used to represent a sprint or a software release. There are a few somewhat complex rules about how project membership, policies and tasks are affected by sub-projects. There is detailed coverage in the Phabricator Projects Documentation and we have attempted to explain some of the implications here:

Comparison of Sub-projects vs. Milestones

• Sub-projects have members, milestones do not.
• 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 subproject.
• Tasks can only exist in a single milestone, but can exist in multiple sub-projects.
• Milestones exist as columns within the parent project's workboard, sub-projects have their own workboard.

Sub-projects in detail

• Projects can have sub-projects. A subproject behaves like a regular project, and moving a task between a project and sub-project is the same as moving a task between two unrelated projects, except:
  • Filtering by project matches all Sub-Project tasks.
  • Moving a task from a project to a sub-project does auto-remove the parent project.
• It's very easy to navigate from viewing a sub-project to viewing a project, via the breadcrumb trail (one click, always in the same place, always present; and then a page reload).
• It's possible, and maybe easier than searching, but not trivial, to navigate from projects to sub-projects. You have to click on sub-projects in the menu, wait for page reload, see the list of projects, identify the one you want, click on it, and wait for page reload.
• Sub-projects often appear in the UI as Project > sub-project, but they appear in name completion as Sub-project, so if you name your sub-project "bugs", it will be really confusing in completion.
  • Hopefully we will get this fixed so that completion shows the parent project.
• A task can belong to two different sub-projects within the same project.

Milestones are also regular projects, except:

• They can be a child of a project or sub-project, but can't be a child of another milestone.
• Milestones also appear as columns in their parent project, and so tasks in a project can be moved to milestones via drag and drop.
• A task can't belong to both a project and to a milestone in that project; if it's in the milestone, adding the milestone's parent project to it removes the milestone (but, possible bug, in the UI it still appears in the Milestone's column).
• Milestone names are not directly available in autocomplete. Instead, you see the parent (sub)project, followed by the Milestone name in parenthesis.
• You can't assign a new task to a project and to a milestone in that project in one action; it takes several full steps.
• There's some UI for auto-numbering milestones in sequence.

Story points is now built in to Phabricator

Previously this functionality was provided by a custom field and rPHSP phabricator-Sprint

• All tasks will show a story point field by default
  • A custom form could be created to restrict this per project
• All numeric story points have been transitioned to the new field, the old story points field is now disabled.

Other new features and bugs fixed

• Auto-completion of usernames and projects in all markup fields & comments. (T876)
• Non-members can watch projects(T77228)
• The "Security" field on tasks is now deprecated. Use the "Report security issue" form instead of submitting a regular task with "security" set to "Software security bug."
• It's now possible to make multiple changes to a task from the comment form instead of using the advanced edit form or submitting multiple times.
• Marking a task as resolved no longer re-assigns it (T84833)

Thanks to everyone who helped out testing this release

This couldn't have happened without everyone's help <3

Specifically I'd like to thank:

• @Luke081515 and @Paladox for testing various bugs and generally making helpful suggestions.
• @thcipriani and @fgiunchedi for all of the deployment-related things.
• @ArielGlenn and @chasemp for reviewing, merging and babysitting my patches in rOPUP Wikimedia Puppet.
• @csteipp for reviewing changes to rPHES phabricator-Security.
• @JAufrecht for thoroughly testing sub-projects and milestones. Many of the points above were lifted from his email to the team practices mailing list.
• @DStrine for helping with testing new features and organizing these notes
• @epriestley for going out of his way on several occasions to address the bugs that we have collectively reported upstream, as well as proactively responding to bugs in our own phabricator instance. He's given us a lot of really valuable support and we would be much worse off without his help.