Phabricator/Help

Play media

An overview of the Phabricator documentation on mediawiki.org

If you have questions, ask in the Discussion page. We will improve our documentation based on the feedback received.

For full documentation, see https://secure.phabricator.com/book/phabricator/

§Creating your account

Play media

How to create your Phabricator account with Wikimedia SUL...

Play media

... or with your LDAP / Labs / Gerrit account.

Play media

How to fill your Phabricator profile.

• First, make sure you have a MediaWiki.org account:
  • Many people have a global/single unified login (SUL) account that allows them to log into MediaWiki.org also. You may already be logged in to MediaWiki.org.
  • If not, try logging in with your Wikipedia, Wiktionary, Wikimedia Commons, MediaWiki.org, etc. account.
  • If that doesn't work, try unifying your account.
  • Finally, if you can not unify your account or don't have an account at all yet, signup for MediaWiki.org.
• Go to the Phabricator login page (the link shows as an arrow to a door in the top right when you're logged out).
• Click the sunflower button that says "Login or Register".
• You will be asked by MediaWiki.org to approve connecting.
• Phabricator will ask you for a username. In case of doubt, just use your Wikimedia username. An email address will also be required, but not shown to other users.

Advanced

If you have a wikitech.wikimedia.org account—also known as an LDAP account or Gerrit account—you can also use that to login. The same Phabricator username can have both MediaWiki.org and LDAP connected. This can be a backup, in the unlikely event Wikimedia SUL is not working. Connect your Wikimedia SUL and LDAP accounts to a single Phabricator username! Otherwise you will create two separate Phabricator accounts.

We do not encourage using multi-factor authentication on Wikimedia Phabricator. If you still plan to use it, read the multi-factor authentication guidelines and requirements first.

§Claiming your previous Bugzilla and RT accounts

Note: To attribute past RT work, do this now, even though the imports have not happened yet.

1. Go to your phabricator email settings.
2. Add the email addresses that you used in fab.wmflabs.org, RT or Bugzilla (they are kept private).

Your account activity (comments, reports you created, etc) will be merged into your Phabricator account within the next days. Please be patient as this can take quite some time, depending on how active you were in Bugzilla and RT before. After the process to link your previous, imported contributions to your Phabricator account has finished, you will be e.g. able to search for reports in Phabricator that you had created in Bugzilla before Bugzilla's reports were imported into Phabricator.

§Receiving updates and notifications

Play media

Subscribing to a single task

Play media

Watching a project to receive its notifications (outdated)

Phabricator notifies you about relevant activity, including your own actions. You can fine tune your email preferences to your taste, receiving web notifications only for certain activities, or no notifications at all.

Phabricator offers several tools to receive the notifications you wish to receive.

• If you are interested in a single object (a task, a mockup...) just click Subscribe in their page. Adding a comment will subscribe you automatically.
• If you are interested in all the activity within a project, you can go to the Members page of the project (the "Members" button in the project navigation bar on the left) and add yourself as a member. Afterwards, go to the project homepage (the first button in the project navigation bar on the left) and click Watch Project. (You can also subscribe to projects, which happens automatically when you add yourself as a project member. The difference is that subscribers only get notified for changes if the project is in the task's Subscribers field, not when it is in the Projects field.

You can also define in your Email preferences for which specific actions (e.g. status, owner, priority or subscriber changes) in a task you would like to (not) receive notifications.

§Creating Herald rules for notifications

This is how you create custom notification rules in Wikimedia Phabricator's Herald. Imagine you want to watch all the tasks that are being created:

1. Click Create Herald Rule
2. Select Maniphest Tasks and Personal
3. Give a descriptive name to the rule, i.e. "All New Tasks".
4. In Conditions, select all of, Is newly created?, and is True.
5. In Action, select every time and Send me an email.
6. Save Rule

This is it. From that point, you will receive an email for every task being created. This is probably too much, though. This is how you can filter these notifications:

• If you want to be notified about new tasks only in specific projects, add a New Condition, and then select Projects and include any of, adding the projects you are interested about.
• If you want to be notified about new tasks only from specific users, add a New Condition, and then select Author and is any of, adding the users you are interested about.

You see where is this going. Adapting these rules you can watch the entire activity of a specific project without having to join it, you can watch certain keywords across the entire Phabricator, etc.

§Writing comments and descriptions

Play media

How to format the text that you write in a comment and how to use lists and headers.

Play media

There are several actions that you can perform at the same time that you comment.

Phabricator allows you to post and edit comments and descriptions using text formatting and inserting images or other files; see Uploading file attachments. You can use toolbar at the top of the input text area and you can use Phabricator's Remarkup.

At the end of the page you have a live preview to check whether your text looks as you expect. Popular use of markup includes:

• Mentioning users as in @username will create a link to their profile and will CC them to the task.
• Adding a task number as in T123 will create a link to the task including a hover card. {T123} inserts the title of the task in your text.
• Adding a project name as in #Project will create a link to the project main page.
• If you want to quote text, you can simply add ">" at the beginning. If you want to reply a comment including it as a quote, click the drop down arrow at the right end of the comment you want to reply.
• If you want to display an uploaded mockup image file, e.g., like M123, embedded in your comment, write {M123}.
• If you want to create an external link, e.g. [https://www.mediawiki.org example] in wiki markup, use [[ https://www.mediawiki.org | example ]] including the whitespaces in Phabricator.
• If you want to add a web address (URL link) in a comment for example to provide a testcase, it is highly recommended to copy and paste the full web address from your web browser's address bar, e.g., https://www.mediawiki.org/wiki/Project:Support_desk instead of mw:Project:Support desk. Interwiki prefixes like mw: are not supported in Phabricator and most customizations that Bugzilla had neither, e.g., Gerrit changes should be pasted as full web addresses too.

Note that Phabricator's own markup language is different from MediaWiki's markup. The upstream phabricator instance hosts a Remarkup Reference for Phabricator's own markup language.

§Creating a task

Play media

Ways to create a task.

Play media

How to edit a task already created.

There are three ways to create a task, depending on the information you want to carry:

• Plain new task: click the + button or the Create Task link located at the top right. You will get a blank form.
• A subtask of an existing task: click the Create Subtask link located in the right column of the current task. The dependency between both tasks will be set, and some values of the parent task will be carried by default (Assigned To, CC, Priority, Projects). Subtasks will be listed in the parent task, sorted by most recently updated.
• A similar task to the one you just created: after creating a task, a Similar Task link is offered at the top right corner. Click it to prefill Assigned To, CC, Priority, and Projects with the same values.

Fill the form, leaving the fields you are not sure about unchanged.

§Selecting projects

In order to relate a task with a project that uses Phabricator, you just need to start typing its name in the Projects field and select the project from the list of matching projects (the list will only show five matching projects). You can add one or more projects to the Projects field. If you are unsure, you can also leave it empty — triagers will take care of tasks that have no project set. There is a (long) list of projects available. Press Edit Query to search for projects.

§Setting task priority

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. See Phabricator project management for details.

§Using e-mail

You can also create tasks by sending e-mail to [email protected]. The subject will be used as task title, the body will be used directly as is, and attachments will be included on the task. To select a project, use its hashtag somewhere in the body, e.g., #mediawiki-core.

Note: if your email signature is not formatted following de facto standards (including "-- " to be separated from the body text) it will be posted as well. You are encouraged to remove private information from your signature in your first attempt, just to be sure.

§Passing certain values in the task creation URL

Project wikipages which offer a "Report a bug in Phabricator" link can pass numerous values via URL parameters appended to the generic task creation link such as:

• projects=project-name1,project-name2
• assign=username
• title=Title%20of%20task
• description=Description%20of%20task
• template=XXXX
• priority=[100, 90, 80, 50, 25, 10]

Prefix your properties with "?" and use "&" to chain properties together.

Example

https://phabricator.wikimedia.org/maniphest/task/create/?projects=Beta-Feature&title=Hovercards:&priority=10

Would create a new task with the tag "Beta-Feature" and prefix the title with "Hovercards:" and give a priority of "Lowest".

§Uploading file attachments

Play media

How to upload files.

There are several ways to upload files: You can add a file (for example a screenshot) to a comment or a task description via drag and drop with your mouse. Users can also copy and paste images via the clipboard functionality of their system.

If this is not available on your system you can use phabricator:file/upload and refer to the file number (like "123") that is shown after a successful upload by writing F123 in a comment. This will create a link to the file. To include the file in the comment, enclose the ID in curly brackets: {F123}. If you have to upload files frequently and consider the currently available options uncomfortable, you could also add a text panel to your homepage with a direct link.

Advanced users could also use "arc upload" which provides an F number that can be used via {Fxx} syntax to embed in a comment.

Note that you cannot upload a file and then decrease the access level to the file (e.g linking it to a restricted security ticket). You would have to delete the file and reupload it with stricter access permissions. It is recommended to upload files which should have restricted access together with the creation of a restricted (security) ticket.

If you ever need to delete a file that you uploaded, open the phabricator:file/ overview, select "Authored", select the file and click "Delete File" in the sidebar.

§Searching for items

Play media

Using Phabricator's basic search field in the upper corner

Play media

Using Maniphest's advanced search

Phabricator consists of several applications (task management in "Maniphest" being one of them, and in the future also code review and other applications). The search field in the upper corner allow searching across all these applications. For a search with advanced search criteria across applications, use the Advanced Search.

§Searching for tasks and bug reports

There is also an advanced search per application. To only search for tasks/bug reports, use the Advanced Search in Maniphest. Examples for the advanced search: To get a list of tasks which were created in the last 24 hours, set the "Created After" field to "-24 hours" or "-1 day". Note that "Updated Before" actually means "Last updated before" and that absolute date values like "2014-11-26" refer to UTC time while your time zone setting might be different. (Searching for tasks that got closed within a certain timeframe is not supported - use Reports as a workaround by setting the "Recently Means" value and checking the "Recently Closed" column for your product.)

Maniphests offers links to some predefined search queries. For example, click authored to get a list of tasks that you have created.

Search query URLs are stable so you can save and reuse them. You can share the link in your web browser's address bar with other users, e.g. via posting the link on a wikipage.

Note that some common queries are also available in the "Activity" tabs on the phabricator frontpage.

§Defining your default search parameters

By default, the search field in the top bar of Phabricator searches all types of documents (tasks, change sets, ...).

Users can change which types of documents are searched for by default by dragging their preferred search to the top of their list of saved searches. Running an advanced search and saving it as a custom query will also place that custom query on top of this list of searches.

§Finding the Maniphest task corresponding to a Bugzilla bug number

All Phabricator tasks migrated from Bugzilla have a Reference field that contains a value "bz" followed by the number of the equivalent report in Bugzilla. If you want to search the task corresponding to a specific Bugzilla report, use the Reference field in the advanced search or just add 2000.

§Custom queries in Maniphest

Play media

Creating and saving custom queries in Maniphest

Maniphest allows for you to save custom queries for easier access and locating of tasks. This requires being logged in.

You can do so by first going to one of the pre-saved queries and editing the query parameters. For example, take the query "All tasks" and click the "Edit Query" button to adjust its parameters.

Saved custom queries can be accessed anytime in the side bar and edited as per your needs. It allows you to limit your search to different categories including but not limited to: Date created, assigned to, priority, status of the task and many more.

Example

You want to view tasks which are in the project Human-Resources, authored by a specific author, assigned to you, and with the priority Needs Triage. Enter Human-Resources in the In all Projects section, enter your username in the Assigned to section, enter the author's name in the Authors section and finally, enable the Needs Triage checkbox in the Priority section. After doing so, click the Search button to see the list of tasks. To save this query, simply click the Save custom query button and enter a name for your query. Afterwards, it will be displayed in the side bar under Queries.

§Creating your dashboard

The phabricator homepage is in fact a dashboard that you can customize. Dashboards are made out of panels. If you find a (public) dashboard in the dashboard list that you like, you can start from it ( Manage Dashboard > Copy Dashboard) and then reuse or create others panels you want to appear on it. There are three types of panels:

• Text panels: a free-form box where you can type any static content. This is an easy way to collect your dearest shortcuts.
• Query panels: a wide collection of predefined search queries allow you to include all kinds of lists to a panel. You can also create and save your own queries using the advanced search tools, and then you can include those saved queries in panels. For instance, you can have a panel showing the combined list of oldest untriaged tasks in the projects you are involved.
• Tab panels: not enough space? a tab panel allows you to include several panels in different layers, using tabs.

You can add and position the panels in a dashboard. Then you can install your dashboard, which will make that dashboard your own homepage. You can have additional dashboards with more panels, but only can substitute your homepage. If you are really into dashboard and you have a bunch of them, you can link to them from a text panel in your homepage.

§Batch Edits

Phabricator offers the possibility to perform batch edits for tasks. At the end of any Maniphest search query you will find a "Batch Edit Selected" to edit all the tasks you have selected using Shift-Click. Users willing to use this feature need to join the Triagers group.

§Statistics

Phabricator offers tables showing the open tasks by priority and by either user or project. Apart from that, Phabricator doesn't support further statistics, metrics, charts, reports (e.g. over time) or however you may call them, whether built-in or via an API.

§Creating a project

In Phabricator projects are tags, tags are projects. There is no tree hierarchy, and there are no subprojects, yet. Tasks can be assigned to more than one project, and they can also be submitted without assigning them to any project.

§When do you need a project?

In general, you need a project...

• when you have a established team running one or several projects (start here, ask more only when you need more)
• when you need a workboard (i.e. a sprint)
• when you need a tag or keyword to organize a type of task that can be part of any project (i.e. "Accessibility")

§Requesting a new project

See Phabricator/Requesting a new project

§Restricting access to tasks

Please see Phabricator/Security for a general overview and Phabricator/Creating and renaming projects#Policy for default project settings.

§MediaWiki templates and interwiki links

Tracked in Phabricator ^(?)
Task T177 Resolved

• You can link to Phabricator tasks from wiki pages using phabricator: and its shorter version phab:, i.e., [[phab:T454|example]] generates example.
• Template:Tracked has been updated to include links to Phabricator objects — see at the right how {{Tracked|T177|resolved}} renders.
• Template:Phabricator is also available; {{Phabricator|T176}} generates Task T176.

Existing Bugzilla interwiki links and templates will still work, because those links will continue to point to bugzilla.wikimedia.org which will redirect them to the converted Phabricator task.

§Diffusion

Further information: Phabricator/Diffusion

Diffusion is the Phabricator repository browser and repository management tool. Eventually we want to replace Gerrit for code review and repository management, and gitblit for repository read-only mirroring. Right now, we're mirroring some of our Git repositories to Phabricator for demonstration purposes.

Diffusion is integrated with the other tools in the Phabricator suite. For instance:

• When you commit Differential revisions to a tracked repository, they are automatically updated and linked to the corresponding commits;
• You can add Herald rules to notify you about commits that match certain rules;
• In tasks and other places, you can automatically link to commits.

§Other links

• Other subpages
• OAuth consumer phabricator-production, use Special:OAuthManageMyGrants to manage connected apps.
• Phabricator etiquette