Created page with "Fabrîqetor/Alîkarî"
New page
<languages />
Dear Phabricator user, if you have questions, just ask in the [[Talk:Phabricator/Help|Discussion]] page. We improve our documentation based on the feedback received.
For a high level understanding of Phabricator, click the link that follows. Or keep reading this page to dive right in and get started.
[[Special:MyLanguage/Phabricator/High Level Phabricator Concepts|What is Phabricator and what does it do?]]
== Creating your account and notifications ==
[[File:Making your Wikimedia Phabricator account.webm|thumb|How to create your Phabricator account with Wikimedia SUL...]]
[[File:How to create an account on WikiMedia Phabricator using wikitech credentials.webm|thumb|... or with your LDAP / Labs / Gerrit account.]]
[[File:Phabricator User-Page Screencast.ogg|thumb|How to fill your Phabricator profile.]]
* First, make sure you are {{special|UserLogin|returnto|Phabricator/Help|logged in}} to Wikimedia.
** If you don't have a Wikimedia account yet, {{special|UserLogin|returnto|Phabricator/Help&type=signup|sign up}} for one.
* Go to the [[phabricator:auth/start/|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, but note that Phabricator username cannot include non-Latin characters such as العَرَبِيةُ or 中华民族. An e-mail address will also be required, but not shown to other users.
* Click on '''Profile''' (top right) > '''Edit Profile''' and set your Also Known As (for example, to your full name) to make it easier to search for you.
; Advanced
:If you have a [https://wikitech.wikimedia.org/ wikitech.wikimedia.org] account — also known as an LDAP account or Gerrit account — you can also use that to log in. 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. [[phab:settings/panel/external/|'''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 [[Phabricator/Help/Two-factor Authentication Resets|multi-factor authentication guidelines and requirements]] first.
=== Claiming your previous Bugzilla and RT accounts ===
[[Phabricator/Help/Reclaim_Bugzilla_and_RT_accounts|Follow the link here.]]
=== Receiving updates and notifications ===
[[File:How_to_subscribe_to_a_single_task_in_Phabricator.webm|thumb|Subscribing to a single task]]
Phabricator notifies you about relevant activity, including your own actions. You can fine-tune your [[phabricator:settings/panel/emailpreferences/|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 <code style="font-size:smaller">Subscribe</code> in its page. Adding a comment will subscribe you automatically.
* If you are interested in all the activity within a project, you can click <code style="font-size:smaller">Join Project</code> on the project summary page or go to the <code style="font-size:smaller">Members</code> 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 <code style="font-size:smaller">Watch Project</code>. 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 <code style="font-size:smaller">Subscribers</code> field, not when it is in the <code style="font-size:smaller">Projects</code> field.<ref>[https://secure.phabricator.com/T6113#76710 Unclear difference between "Watch Project" and "Subscribe"], on the upstream Phabricator instance</ref>
<!-- * Still unhappy? Meet [https://secure.phabricator.com/book/phabricator/article/herald/ Herald], a powerful tool that will send you notifications based on specific rules (e.g. when a keyword is mentioned in certain projects).
There is even more at the [https://secure.phabricator.com/book/phabricator/article/mail_rules/ Managing Phabricator Email] user guide. -->
You can also define in your [[phab:settings/panel/emailpreferences/|Email preferences]] for which specific actions (e.g. status, owner, priority or subscriber changes) in a task you would like to (not) receive notifications. Prolific users might want to reduce email settings to a minimum, such as in [[:File:Phabricator email settings panel.png]]
=== Creating Herald rules for notifications ===
[[Special:MyLanguage/Phabricator/Help/Herald Rules|Follow this link]] to learn how to create '''custom (personal)''' notification rules in [[phab:herald/|Wikimedia Phabricator's Herald]]. This is a more advanced option and can be difficult to use.
== Creating a task ==
{{TNT|Main|How to report a bug}}
[[File:Explanation_on_creating_a_task.webm|thumb|Ways to create a task.]]
[[File:Wikimedia Screencast.webm|thumb|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 <code style="font-size:smaller">[[phabricator:home/create/|+]]</code> button or the [[phabricator:maniphest/task/create/|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.
=== Formatting ===
Phabricator supports some formatting in text areas. [https://secure.phabricator.com/book/phabricator/article/remarkup/ See this help about formatting in Phabricator.]
=== 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 also search for projects by clicking the magnifier icon in the ''Projects'' field. 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) [[phabricator:project/query/active/|list of projects]] available. Press <code style="font-size:smaller">Edit Query</code> to search for projects. (This list is also available at [[Special:MyLanguage/Phabricator/Projects|Phabricator/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#Setting_task_priorities|Phabricator project management]] for details.
=== Using e-mail ===
You can also create tasks by sending e-mail to [mailto:task@phabricator.wikimedia.org task@phabricator.wikimedia.org]. 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., <code style="font-size:smaller">#mediawiki-core</code>.
''Note: if your e-mail 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 ===
"Report a bug in Phabricator" link can pass numerous values via URL parameters appended to the [[phab:maniphest/task/create|generic task creation link.]]
This is a very advanced feature. [[Special:MyLanguage/Phabricator/Help/Task_Creation_URL|Learn more here.]]
=== Writing comments and descriptions ===
[[File:Comment_mark_up_in_phabricator.webm|thumb|How to format the text that you write in a comment and how to use lists and headers.]]
[[File:Gciwikimedia4.webm|thumb|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|Uploading file attachments]]. You can use toolbar at the top of the input text area and you can use Phabricator's ''Remarkup''.<ref name="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 <code style="font-size:smaller">@username</code> will create a link to their profile and will CC them to the task.
* Adding a task number as in <code style="font-size:smaller">T123</code> will create a link to the task including a hover card. <code style="font-size:smaller">{T123}</code> inserts the title of the task in your text.
* Adding a project name as in <code style="font-size:smaller">#Project</code> will create a link to the project main page.
* If you want to quote text, you can simply add "<code style="font-size:smaller">></code>" 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 <code style="font-size:smaller">M123</code>, embedded in your comment, write <code style="font-size:smaller">{M123}</code>.
* If you want to create an external link, e.g. <code style="font-size:smaller"><nowiki>[https://www.mediawiki.org example]</nowiki></code> in wiki markup, use <code style="font-size:smaller"><nowiki>[[ https://www.mediawiki.org | example ]]</nowiki></code> 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., <code style="font-size:smaller"><nowiki>https://www.mediawiki.org/wiki/Project:Support_desk</nowiki></code> instead of <code style="font-size:smaller">mw:Project:Support desk</code>. Interwiki prefixes like <code style="font-size:smaller">mw:</code> are not supported in Phabricator and most customizations that Bugzilla had neither, e.g., Gerrit changes should be pasted as full web addresses too.
* If you want to paste lines of code, add a line with three backticks before and after the code: <code style="font-size:smaller"><nowiki>```</nowiki></code>. Or [[phab:paste|create a Paste]] and link to the Paste from the task.
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.<ref name="remarkup">[https://secure.phabricator.com/book/phabricator/article/remarkup/ Remarkup Reference], on the upstream Phabricator instance</ref>{{anchor|Uploading file attachments}}
=== Uploading file attachments ===
[[File:Uploading_files.webm|thumb|How to upload files.]]
There are several ways to upload files: You can add a file (for example a screen photo) 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 [[phab:file/upload/|phabricator:file/upload]] and refer to the file number (like "123") that is shown after a successful upload by writing <code style="font-size:smaller">F123</code> in a comment. This will create a ''link'' to the file. To ''include'' the file in the comment, enclose the ID in braces: <code style="font-size:smaller">{F123}</code>. If you have to upload files frequently and consider the currently available options uncomfortable, you could also add a [[phab:dashboard/|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 <code style="font-size:smaller">{Fxx}</code> 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.
== Project management in Phabricator ==
[[Phabricator/Project management|If you maintain or manage a project, please follow this link for more details.]]
=== Tasks and workflow ===
Each Phabricator Workboard has a column flagged as "Default", and any new task added to that Project will start off in that column.
=== Blocking tasks ===
Tasks can block, or be blocked by, any number of other tasks. This feature can be used to accomplish a few different things:
* Blockers. A task might simply be blocked by another task, representing a dependency (see [[Phabricator/Project management#Tasks that cannot be worked on yet]] on how to add a blocking task).
* Subtasks. A parent task would be blocked by its subtasks. (There is no other way to mark parent/subtask relationships).
* Tracking. A "workless" task blocked by several tasks might be tracking a collection of tasks within a release or other time period (see [[Team Practices Group/Phabricator tips#"Tracking" Tasks|#"Tracking" Tasks]] below).
* Approval. Several tasks (such as draft team goals) might be blocked by a single task which represents the draft tasks getting approved, after which those draft goals are now real goals.
NOTE: There is a "Create Subtask" feature. In addition to setting up the correct blocking/blocked-by relationship, it also caries the CC (subscription) list into the new subtask. Once the subtask has been created, it is simply a blocking task. The explicit "subtask" state is not preserved.
=== Prioritization ===
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.
Within a Workboard, Tasks can be arranged in a priority order within a column. Choose "Natural" sort, and then 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 also be sorted by the underlying Priority field, 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.
=== Assignment ===
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.
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 [[Team Practices Group/Glossary#Cookie-licking .28Licking the Cookie.29|"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.
=== "Done" ===
Each Task has a Status field, which includes the state of Resolved. Resolved tasks are often hidden from Workboards, and 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 {{#expr: {{CURRENTYEAR}} +1 }} 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.
=== "Tracking" tasks ===
This term was brought over from Bugzilla, where it had a specific meaning: A task which was blocked on other tasks, but which itself did not represent any work, and which was not tied to a specific release/date. An example might be a Task named "Clean up the documentation", which might then have a variety of subtasks, each of which would describe specific work to be done. These "Tracking" Tasks tended to stick around for a long time (or forever), as their subtasks would get resolved but new ones would get created. In Phabricator, it would be better to create a Project (tag) to categorize this type of work.
Note, however, that there are other types of work-less umbrella tasks which do still make sense in Phabricator. Notably, "Release" tasks. An upcoming release could be represented by a Task, which lists as subtasks (aka blocking tasks) all the actual work tasks which are targeted for that release. Once the release goes out, it can be resolved. A similar use would be to have a task which represents a teams overall goals for the quarter, and then each goal might (or might not) be a blocking subtask.
== Searching for items ==
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 allows searching across all these applications.
[[Special:MyLanguage/Phabricator/Simple_Search_In_Phabricator|Click here for a description of simple search features.]]
However it is very limited. It has its own version of an advanced search. However this does not compare to the full feature set and flexibility of Maniphest.
=== Using Maniphest (Advanced Search) ===
Maniphest is a tool which allows users to make detailed queries. Users can refine a query using multiple parameters. Queries can also be saved and managed.
New users will find several saved queries preset inside Maniphest. Clicking on the "Advanced Search" will bring up a new search page.
[[Team Practices Group/Phabricator tips/Maniphest|Click here for a detailed Maniphest walkthrough.]]
== Advanced features ==
=== Using Dashboards ===
Dashboards are specially designed home pages which can display a wide range of custom information. They can be created, managed and shared between users.
[[Team Practices Group/Phabricator tips/Dashboards|Click here for a detailed Dashboard walkthrough.]]
=== Batch edits ===
Phabricator offers the possibility to perform mass/bulk edits for tasks. At the end of any [[phab:project/profile/13/|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 [[phab:project/profile/13/|Triagers]] group.
=== Personal lists of items ===
The "Flag For Later" functionality offers marking objects (like tasks or revisions) which "you want to remember to look at later". Eight flag colors are available. Flags are personal and private so your lists cannot be shared with others. Your flagged objects are listed on Special:MyLanguage/Phabricator/Tokens. They can be searched by color or object type, in contrast to [[Special:MyLanguage/Phabricator/Tokens|tokens]].
=== Creating a project ===
In Phabricator projects are tags, tags are projects. There is no tree hierarchy, and there are no subprojects, ''yet''.<ref>[https://secure.phabricator.com/T3670 T3670 (subprojects, requires login)], on the upstream Phabricator instance</ref> 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 an 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 (for example "Accessibility")
==== Requesting a new project ====
See [[Phabricator/Requesting a new project|Phabricator/Requesting a new project]].
=== Restricting access to tasks ===
Please see [[Phabricator/Security]] for a general overview and for the "Security" dropdown option in tasks. See [[Phabricator/Creating and renaming projects#Policy]] for default project settings (and using Spaces).
=== MediaWiki templates and links ===
{{Tracked|T177|resolved}}
* You can link to Phabricator tasks from wiki pages using <code style="font-size:smaller">phabricator:</code> and its shorter version <code style="font-size:smaller">phab:</code>, for instance <code style="font-size:smaller"><nowiki>[[phab:T454|example]]</nowiki></code> generates [[phab:T454|example]].
* [[Template:Tracked]] has been updated to include links to Phabricator objects — see at the right how <code style="font-size:smaller">{{tlx|Tracked|T177|resolved}}</code> is rendered.
* [[Template:Phabricator]] is also available; <code style="font-size:smaller">{{tlx|Phabricator|T176}}</code> generates {{Phabricator|T176}}.
Existing Bugzilla links and templates will still work, because those links will continue to point to <tt>bugzilla.wikimedia.org</tt> which will redirect them to the converted Phabricator task.
=== Using Conpherence ===
[[phab:conpherence/|Conpherence]] is a Phabricator application that enables private conversations between two or more users, similar to instant messaging and private chat rooms. No team is known to use this. It may conflict with other communication channels. [[Phabricator/Using Conpherence|To learn more click here.]]
Conpherence has an optional persistent window/column that can be shown and hidden with the keyboard button "\". Users may accidentally activate this feature, and it can only be hidden again by using the "\" key (there is no graphical UI feature to close it).
=== Statistics ===
Phabricator offers tables showing the [[phab:maniphest/report/project/|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.<ref>[https://secure.phabricator.com/T1562 T1562 (statistics, requires login)], on the upstream Phabricator instance</ref>
=== Diffusion ===
:''{{see|Phabricator/Diffusion}}''
Diffusion is the Phabricator repository browser<ref>[https://secure.phabricator.com/book/phabricator/article/diffusion/ Diffusion repository browser user guide], on the upstream Phabricator instance</ref> 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.
== Other links ==
<references />
* Other {{special|prefixindex/Phabricator/|stripprefix|1|subpages}}
* [[Special:OAuthListConsumers/view/211867c109f5b97b392082965a1abd4b|OAuth consumer phabricator-production]], use [[Special:OAuthManageMyGrants]] to manage connected apps
* [[Bug management/Phabricator etiquette|Phabricator etiquette]]
[[Category:Phabricator{{#translation:}}]]