Phabricator/Help

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

Link to official docs: https://secure.phabricator.com/book/phabricator/

Signing in
(These instructions are valid for legalpad.wikimedia.org and the upcoming Wikimedia Phabricator instance in production.)

Users sign in to Wikimedia Phabricator using their Wikimedia (mediawiki.org, Wikipedia...) account. If you don't have one, get one.

It is possible to add several e-mail addresses to a Phabricator account (and they are kept private). This allows users to claim their Bugzilla accounts. It is not required that any of these e-mails be associated to a SUL account on Wikimedia wikis.

Receiving updates and notifications
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. There is even more at the Managing Phabricator Email user guide.
 * If you are interested in a single object (a task, a mockup...) just click  in their page. Adding a comment will subscribe you automatically.
 * If you are interested in all the activity within a project, you can  it and then   to it.
 * If this is not enough, you can click, which includes references to this project posted anywhere else. This is recommended for core team members.
 * Still unhappy? Meet Herald, a powerful tool that will send you notifications based on specific rules (e.g. when a keyword is mentioned in certain projects).

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: 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: 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.
 * 1) Click
 * 2) Select   and
 * 3) Give a descriptive name to the rule, i.e. "All New Tasks".
 * 4) In , select  ,  , and.
 * 5) In , select   and.
 * If you want to be notified about new tasks only in specific projects, add a, and then select   and  , adding the projects you are interested about.
 * If you want to be notified about new tasks only from specific users, add a, and then select   and  , adding the users you are interested about.

Writing comments and descriptions
Phabricator allows you to post and edit comments and descriptions using text formatting and inserting images or other files (FIXME: create instructions for each of these actions). You can use toolbar at the top of the input text area and you can use Phabricator's own markup. Popular use of markup includes: At the end of the page you have a live preview to check whether your text looks as you expect.
 * 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. In task descriptions it will add the project to the Projects field.
 * 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.

Note that Phabricator's own markup language is different from MediaWiki's markup. If you want to add a web address (URL link) in a comment (for example to provide a testcase), it is highly recommend to copy and paste the full web address from your web browser's address bar (like "https://www.mediawiki.org/wiki/Project:Support_desk") instead of using MediaWiki markup (like "mw:Project:Support desk").

Creating a task
There are three ways to create a task, depending on the information you want to carry: Fill the form, leaving the fields you are not sure about empty.
 * Plain new task: click the + 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).
 * 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.

Selecting projects
In order to relate a task with a project, you just need to start typing its name in the Projects field and select the project from the list of possible options. 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 orphan tasks. There is a list of projects available.

Uploading file attachments
There are several ways to upload files: You can add a file (for example a screenshot) to a comment via drag and drop with your mouse. If this is not available on your system you can use https://phabricator.wikimedia.org/file/upload/ and refer to file number (like "123") that is shown after successfully having uploaded by writing "F123" in a comment. Users can also copy and paste images via the clipboard functionality of their system. 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.

Searching for items
TODO: Specific search in applications (Maniphest tasks) vs. global search; querying for a specific timespan via "Created After" on /query/advanced/ allows relative time spans in strtotime formats, like "-24 hours" or "-1 day"; Search query URLs are stable and can also be used by other users (e.g. when posting them on a wikipage); query for tasks that you reported can be done on https://phabricator.wikimedia.org/maniphest/query/advanced/; some common queries are also available in the "Overview" dashboard on the Phabricator frontpage.

Claiming your previous Bugzilla and RT accounts
Note: This section only applies after RT and Bugzilla tickets have been imported into Phabricator. This import has not happened yet.

Either or
 * 1) Go to https://phabricator.wikimedia.org/settings/panel/email/.
 * 2) Add the email addresses that you used in RT and Bugzilla.
 * 1) In the upper right corner, click your gravatar icon (between the search field and the + button) to go to your user profile.
 * 2) Click "Edit Profile".
 * 3) Enter the email address that you used in Bugzilla or RT in the corresponding fields.
 * 4) Your account activity (comments, reports you created, etc) will be merged into your Phabricator account within the next 48 hours. After that timeframe you are e.g. able to search for reports in Phabricator that you had created in Bugzilla before Bugzilla's reports were imported into Phabricator.

Creating a project
In Phabricator projects are tags, tags are projects. There is no tree hierarchy, and there are no subprojects (these might come in a near future, though). 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
In order to keep some sanity and consistency, projects can be created only by the Phabricator team. Anybody can request a new project. Just create a new task under the "Phabricator" project, specifying the project name and description, which ideally would include a link to the project main/wiki page.

Project naming guidelines:
 * Think of the shortest name that users can find easily typing ahead.
 * Ideally one word, otherwise multiple words must be connected with dashes.
 * Unnecessary use of frequent words like "Wikimedia" or "MediaWiki" should be avoided.
 * Title case by default.

Good: Phabricator, MediaViewer, Code-Review, Phabricator-Production-Instance... Bad: Wikimedia Phabricator, MediaViewer-for-MediaWiki, Code Review for Phabricator...

The default access policies for Wikimedia projects and tasks are: If your project requires more restrictive permissions, please explain your reasoning in your request.
 * visible to everybody (no login required)
 * editable by all registered users
 * joinable by all registered users

If you belong to a team that will manage several projects, then the first step is to create a project for your team.

MediaWiki templates and interwiki links
Existing Bugzilla interwiki links and templates will still work, because those links will redirect to the equivalent Phabricator tasks.
 * You can link to Phabricator tasks from wiki pages using  and its shorter version   (i.e. example generates example).
 * Template:Tracked has been updated to include links to Phabricator objects — see at the right how renders.
 * Template:Phabricator is also available; generates.