User:AKlapper (WMF)/Sandbox/T226062

Audio script for initial (September 2020) version of Phabricator tutorial videos. See T226062 for more context.

To be used in combination with https://gitlab.com/aklapper/phabricator-lorem-ipsum plus further manual customizations on a local Phabricator test instances.

VIDEO-01: What is phabricator.wikimedia.org?
█▉▶CUT-01-01

▶🖵 Show custom slide

Welcome to this video. It is part of a series of tutorials to explain basic concepts of phabricator.wikimedia.org.

█▉▶CUT-01-02

▶🖵 Show default frontpage

Phabricator is a work tracking and project management tool, used by the Wikimedia movement and other organizations.

Maybe you have used Jira, Asana, Trello, or Mingle before. They are similar pieces of software for tracking work.

Phabricator allows you to manage pieces of work that someone could or should work on.

In software development these are often bug reports or feature requests.

In Phabricator, these pieces of work are called tasks. Sometimes people call them tickets or cards.

Wikimedia's Phabricator is primarily used for software projects. It is also used by teams to organize their work.

Phabricator allows collaboration and transparent communication between people and across teams, and a shared backlog of tasks.

█▉▶CUT-01-03

▶🖵 Show Phab help page

In the Wikimedia movement, we work in the open whenever feasible. Anyone can create an account and create tasks or comment.

The central documentation page for Wikimedia Phabricator is the page "Phabricator/Help" on mediawiki.org.

VIDEO-02: Tasks
█▉▶CUT-02-01

▶🖵 Show custom slide

Welcome to this video. It is part of a series of tutorials to explain basic concepts of phabricator.wikimedia.org.

█▉▶CUT-02-02

▶🖵 Show task "Repair leaking pipe in bathroom"

The most relevant concepts to understand are tasks and projects. Tasks get associated with project tags.

A task in Phabricator defines some work to do. It could be a software bug report or a feature request, for example.

A task always has a Summary at the top.

Below the summary is the Status. The status can be Open, Stalled, Resolved, Declined, Invalid, or Duplicate.

█▉▶CUT-02-03

▶🖵 Show https://www.mediawiki.org/wiki/Bug_management/Bug_report_life_cycle

For more info, see Task status and life cycle on the help page which brings you to the life cycle page.

Note that "Stalled" means "Blocked". A task is not stalled just because nobody is currently working on the task.

█▉▶CUT-02-04

▶🖵 Go back to task "Repair leaking pipe in bathroom"

Next to the status is the Priority of the task. This expresses how urgent the task is.

Setting the priority can be tricky, because a task can be in more than one project.

Priorities should reflect reality and do not cause it. That often means that the task priority should be low.

Some maintainers and teams do not use the Priority field, and use columns on their project workboard for planning instead.

For more info, see Prioritization on the help page.

Next to Status and Priority is the visibility of the task. By default, tasks are public.

If a task should not be public, then see Restricting access to tasks on the help page.

A task should also have a description with more information which allows anyone else to understand what the task is about.

▶🖵 Select "Edit Task" in sidebar

The task description and other aspects can be edited by selecting "Edit Task" in the sidebar.

This can be helpful to reflect progress on a task or update the task scope, based on added comments.

█▉▶CUT-02-05

▶🖵 Go back to task view

In the sidebar are the associated project tags. If a project has a workboard, the workboard column is shown in brackets.

These project tags allow others to find and see the task when they look at tasks in a certain project.

The project could be a codebase or a team. Clicking on a project tag brings you to that project.

The sidebar also shows the individual assignee of a task.

This is the person who works or plans to work on the task.

Most tasks do not have an assignee. This is normal:

Anyone can create tasks. Many tasks will stay open because nobody has decided yet to work on them.

You also see individual subscribers who receive notification updates about the task.

Below the description, the "Related Objects" box shows dependencies between tasks as a hierarchy graph.

Further below are comments on the task added by any interested people.

▶🖵 Scroll down to show Gerritbot comment

If somebody created a patch in Gerrit for a public task and followed the commit message guidelines,

then Gerritbot will automatically comment and add the "Patch-For-Review" project tag.

█▉▶CUT-02-06

▶🖵 Scroll up in that task again, then click "Edit Task"

Tasks can have due dates. Due Dates can be set by selecting "Edit Task" in the sidebar.

Tasks can have story points if you do agile development.

Tasks can be classified via subtypes. For example, a task can either have a Bug Report subtype or a Feature Request subtype.

▶🖵 Scroll down, click "Add Action…" dropdown

The subtype is set when creating the task. The subtype can be changed via the "Add Action…" menu above the comment field.

█▉▶CUT-02-07

▶🖵 Click Favorites in top bar

To create a new task, click the Favorites icon in the top bar.

The entries in your Favorites menu can differ from this video. Some entries depend on the permissions of your account.

You can customize your menu entries via "Edit Favorites".

To create a public task, select "Create Task".

▶🖵 Select "Create Task" in Favorites top bar

This option brings you to a blank default form.

There are also other, specialized forms to create tasks with prefilled values or show specialized fields for some teams.

If you create a task for the first time, first visit and read the link in the box at the top.

Enter the task summary. It should be clear and specific.

▶🖵 Enter in summary, from one clipboard buffer: ▶🖵-PASTE Change ringtone of house doorbell from Beethoven's Ninth to a shorter Symphony

Enter the task description. It should allow anyone else to to understand and reproduce, not only members of your team.

▶🖵 Enter in task desc, from another clipboard buffer:

▶🖵-PASTE **Steps to reproduce:** ▶🖵-PASTE 1. Ring the doorbell ▶🖵-PASTE 2. Listen ▶🖵-PASTE **Expected outcome:** ▶🖵-PASTE A distinctive, short motif is played. An option would be the Fifth Symphony - ta ta ta taaaa! ▶🖵-PASTE **Actual outcome:** ▶🖵-PASTE The Ninth Symphony is played (which is quite long).

▶🖵 Under "Tags" type "House" to add as a project

Add project tags. This task is about the house. Type ahead and select the project that implements the code to be changed.

If you are a member of a team and your team plans to work on the task, then you can also add the project tag of your team.

▶🖵 On the right of the "Tags" field, click magnifier button, then search for "Electricians"

You can search for projects by selecting the magnifier button. This also displays the first sentence of project descriptions.

▶🖵 Select #Electricians project tag

Here we add the #Electricians team project tag, so the task will be shown on the Electricians project workboard.

Do not set a team project tag if unsure. Teams themselves decide which tasks they want to have on their list.

▶🖵 Scroll down

Scroll down and check the task preview. If everything looks fine, press the "Create New Task" button.

▶🖵 Click "Create new task" button

A task should have a scope and definition which allows closing the task at some point.

If a task is never-ending, for example "Maintain the garden", use or create a project tag instead.

█▉▶CUT-02-08

Anybody who is logged in can add comments to a task.

▶🖵 Paste or type comment: @Maria: Probably only the first eight notes?

You can explicitly mention other users by using the @ prefix.

Mentioned users will get subscribed to public tasks. In security tasks you will have to explicitly add them as subscribers.

▶🖵 Add comment, then point to subscribers in the sidebar

For more info, see Formatting and markup on the help page.

▶🖵 Click comment dropdown and quote last comment!

You can quote previous comments via the comment dropdown. Please remove unneeded parts of a quote to keep it readable.

You can also create tasks via email or comment on tasks by replying to email notifications.

Remove unneeded quotations, and use the "-- " standard delimiter to make Phabricator strip your email signature.

▶🖵 Scroll down to comment field of task, click dropdown above

You can access common actions via the "Add Action…" menu at the bottom. These actions are also available via "Edit Task".

▶🖵 Select two of these options, to make fields be displayed

You can change the assignee (for example, to claim a task yourself), project tags, or the task status.

▶🖵 Click "Edit Related Tasks… 🡒 Close As Duplicate"

However, to mark a task as a duplicate, you have to use "Edit Related Tasks… 🡒 Close As Duplicate" in the sidebar.

▶🖵 Click attachment button in comment field

You can upload file attachments, for example a screenshot.

Note that you cannot upload a file and afterwards restrict access to the file. Only administrators can delete files.

For more info, see Uploading file attachments on the help page.

█▉▶CUT-02-09

▶🖵 Go to task "Set up beanpoles so we can grow some green beans"

Dependencies between tasks are called parent tasks and subtasks.

▶🖵 Click "Edit Related Tasks… 🡒 Edit Subtasks", scroll down a bit so dialog is complete on screen!

Subtasks have two semantic meanings: Subtasks either block work on their parent task, or subtasks break up the work

needed to later resolve their parent task. You can edit these dependencies via "Edit Related Tasks…" in the sidebar.

▶🖵 Search for "beanpoles", then save the two subtasks!

Enter words included in the task summary, or directly enter task numbers, like "T123". Choose "Select" and save.

Task dependencies are shown as a hierarchy graph in the "Related Objects" box.

▶🖵 Scroll down, change task status to "stalled"

Here we could also change the task status to stalled, as no work can be done before the subtask has been resolved.

█▉▶CUT-02-10

▶🖵 Click "Edit Related Tasks… 🡒 Create Subtask"

To create a new subtask of an existing parent task, select "Edit Related Tasks… 🡒 Create Subtask" in the sidebar.

▶🖵 Scroll down a bit to show tags and subscribers!

Subtasks inherit the project tags, assignee, and subscribers from their parent task.

Please review and correct data before creating a subtask, to avoid unneeded notifications or confusion.

█▉▶CUT-02-11

▶🖵 Open task "Set up apple tree"

If a task requires several small steps, then you could also use checkbox items in its description instead of subtasks.

If you often create repetitive tasks, consider using a template, URL parameters to fill in fields, or a dedicated Form.

For more info, see Passing certain values in the task creation URL on the help page.

▶🖵 Click Favorites dropdown in top bar

If you use a certain Form more often, then you can add this Form to your Favorites menu in the top bar.

For more info, see Default fields on the help page.

▶🖵 Click Subscribe in the sidebar

You can also subscribe to an individual task, so you will receive notification updates about changes in that task.

▶🖵 Click User menu in top bar, select Settings. Select "Email Preferences" in the sidebar

Depending on your settings under "Email Notifications", you will receive notifications via email or in the top bar on the web.

▶🖵 Hover over notification icon in top bar

For more info, see Receiving updates and notifications on the help page.

VIDEO-03: Projects and workboards
█▉▶CUT-03-01

▶🖵 Show custom slide

Welcome to this video. It is part of a series of tutorials to explain basic concepts of phabricator.wikimedia.org.

█▉▶CUT-03-02

▶🖵 Show task "Repair the broken fence"

In the sidebar of a task you see the project tags associated with the task.

In Wikimedia, we follow a color and tag scheme for project tags. For example, team projects are violet.

For more info, follow Project management on the help page and look at Projects.

Projects are baskets to organize work; for example by code repository, functionality, or by team.

You could also call them labels or tags.

Projects allow everyone to see the work proposed in an area.

A distinct codebase should have its own dedicated project tag, even if you think that only your team will work on it.

▶🖵 Click task's project tag #Garden in the sidebar

Clicking on a project tag brings you to the project view. The exact view depends on the default set for that project.

Projects must have a description. It should allow anyone to understand what the project is about, not only your team.

The very first sentence of a description should be clear and brief, as it is shown in the project search results.

On the left of the project page, you see the sidebar.

Here you can access the project overview page, the workboard, or manage the project.

▶🖵 Click Manage

Under "Manage" you can edit the menu shown in the sidebar.

For example, you could add a link to the project's wiki page or add common search queries to make them available via one click.

Under "Manage" you can also archive a project when it is not used anymore.

When you archive a project, update its description if applicable, for example by which project it has been superseded.

If the archived project would still have open tasks which have no other active project tags, then please

either update the tasks' statuses or add active project tags to the tasks, so the open tasks can still be found.

▶🖵 Click first item (project overview page) in left sidebar to go back to #Garden project overview page

Anybody can make themselves a member of a project. However, for public projects, membership has no particular meaning.

Creating projects requires special rights.

Anybody can request the creation of a project or permissions to create projects themselves.

For more info, see Project management on the help page.

It is also possible to have "Spaces" in which all tasks are access-restricted to a static group of people.

Spaces are in-parallel to projects.

For more info, see Restricting access to tasks on the help page.

▶🖵 Click Workboard in the sidebar on the left

Select "Workboard" in the sidebar for the project's workboard.

▶🖵 Create new workboard on "Garden" project

Projects do not have a workboard by default, so we set it up.

A workboard shows all the tasks which are associated with that project tag as cards.

▶🖵 Drag assigned task "Repair the broken fence" from Backlog to "In Progress" column

Columns can track the progress of a task within a project. They can also be used to subcategorize tasks within a project.

For more info, see Project management on the help page.

Column headers show the number of tasks and their story points.

Tasks can be dragged and dropped from one column to another.

A card shows the task title, the priority via the color strip, the task assignee, and other project tags of a task.

▶🖵 Click cog icon and select "Add Column", call it "In Progress"

You can add, hide, or reorder columns after pressing the cog icon in the upper corner.

▶🖵 Go to upper corner, click Natural (Sort)

In the upper corner of a workboard you can change how tasks are grouped in each column.

▶🖵 Group by priority. Then group by assignee

For example, you can group tasks by priority or by assignee (which is called "owner" here).

▶🖵 Go to upper corner, click "Open Tasks" (filter)

By default, a workboard shows all open tasks. In the upper corner you can change and filter the view.

▶🖵 Click "Assigned to myself"

You can view all tasks, or only tasks assigned to yourself.

▶🖵 Click "Advanced Filter…"

You can also set an Advanced Filter. The search form is the same as in the Advanced Search which will be explained later.

▶🖵 Click workboard "Edit" header column

You can mass-move tasks from one column to another column or to a different project tag via the menu in the column header.

Mass-moving tasks requires special rights. For more info, see Batch edits on the help page.

█▉▶CUT-03-03

▶🖵 Go back to #Garden project overview page

Projects can have subprojects, to split tasks into areas. Subprojects are not shown on their parent workboard.

▶🖵 Select "Food Plants" from the Subprojects listed on the right (!) to get to overview page

The breadcrumbs at the top show the project hierarchy.

▶🖵 Point to list of milestones on the right

Furthermore, projects and subprojects can have milestones.

▶🖵 Select Workboard in the sidebar!

A milestone is shown as a column on the workboard of its parent project.

A task can be in several subprojects but only in one milestone of one parent project.

For more info, follow Project management on the help page and then Parent Projects, Subprojects and Milestones.

█▉▶CUT-03-04

▶🖵 Go to the "Deploy a grumpy dog at the entrance" task on the workboard

For automated actions based on conditions there is Herald.

▶🖵 Show Herald action on that task

For example, when the codebase project tag X is added to a task, a Herald rule also adds team project tag Y to the task.

For more info, see the Herald Rules subpage of the help page.

█▉▶CUT-03-05

▶🖵 Go back to #Garden project tag in the sidebar!

On workboards, automated actions are also possible when a task is dragged and dropped from one column to another.

▶🖵 Click first button in workboard column

These are called Triggers. You could have a trigger which sets a task status or assignee when a task is dragged into a column.

For more info, follow Project management on the help page and look at Columns.

VIDEO-04: Searching and listing tasks
█▉▶CUT-04-01

▶🖵 Show custom slide

Welcome to this video. It is part of a series of tutorials to explain basic concepts of phabricator.wikimedia.org.

█▉▶CUT-04-02

▶🖵 Go to frontpage

The global search is in the upper right corner. By default it searches everything: Tasks, projects, users, commits, etc.

▶🖵 Click search scope in upper search bar

You can narrow the search scope via the dropdown on the left. For example, you can search for tasks only.

▶🖵 Enter "beanpoles" and search!

There is a more powerful Advanced Search for tasks only.

█▉▶CUT-04-03

▶🖵 Go to Frontpage; click Tasks & Bugs in the sidebar, then "Advanced Search" in the sidebar

Go to the frontpage and select "Tasks & Bugs" in the sidebar. Then choose "Advanced Search" in the sidebar.

▶🖵 Enter "title:beanpoles", enter Tags: Garden !

You can combine several search criteria, for example to search in a timeframe or by projects.

If a parent project tag is a search criterion, then the results will also include tasks in its subprojects or milestones.

For more info, see Searching for items on the help page.

▶🖵 Click user name in top bar, then choose Profile

You can also find tasks with which you have interacted recently in your activity log on your user profile.

█▉▶CUT-04-04

▶🖵 Go to Frontpage; click Tasks & Bugs in the sidebar

To see all tasks assigned to yourself across all projects, select "Tasks & Bugs" on the frontpage.

By default, your assigned tasks are shown.

Several other default Global Search Queries are available in the sidebar.

█▉▶CUT-04-05

▶🖵 Go back to previous Advanced Search results: Enter "title:beanpoles", enter Tags: Garden

Going back to our previous search, you can save your custom search query after running it:

▶🖵 Scroll down; press "Save Query"

Press the "Save Query" button at the bottom of the search results.

The new query is listed in the sidebar and will be the default query displayed when you go to "Tasks & Bugs".

▶🖵 Drag a query to a different position; make some other query the default

Under "Edit Queries…" you change the order of sidebar items via drag and drop, and change the default search query.

█▉▶CUT-04-06

▶🖵 Go back to #Garden workboard

When you are on a project workboard, you can also list all tasks in a column as a search query result:

▶🖵 Click "View Tasks as Query" in column header

In the column header dropdown, select "View Tasks as Query".

In the query view, you could now define additional search criteria to exclude some tasks.

Afterwards you can batch-edit your selected tasks if you have the appropriate permissions.

VIDEO-05: Individual productivity
█▉▶CUT-05-01

▶🖵 Show custom slide Welcome to this video. It is part of a series of tutorials to explain basic concepts of phabricator.wikimedia.org.

█▉▶CUT-05-02

▶🖵 Go to #Garden project page

▶🖵 Click "Watch" button on project page

If you are a developer of a project, then you could watch the project to receive notifications on all changes to its tasks.

For more info, see Receiving updates and notifications on the help page.

Notifications can be noisy, so the help page also explains how you can adjust your settings.

█▉▶CUT-05-03

▶🖵 Go to task "Repair the broken fence"

You can create personal lists of specific tasks by selecting "Flag For Later" in the sidebar of a task.

▶🖵 Select "Flag For Later", choose Red!

These flags are like pages on your on-wiki watchlist.

▶🖵 Go to front Frontpage, select More Apps, select Flags.

To see your list of flagged tasks, go to the frontpage. Select "More Applications" in the sidebar and then "Flags".

█▉▶CUT-05-04

▶🖵 Show https://phabricator.wikimedia.org/dashboard/view/125/

You can also customize your frontpage by adding and creating dashboards. Here you see a real example.

For more info, see Using dashboards on the help page.

VIDEO-99: Standard end to include in all videos above
█▉▶CUT-99-01

▶🖵 Show last but one custom slide with the two Help links

For feedback or questions about Wikimedia Phabricator, use the discussion page of "Phabricator/Help" on mediawiki.org.

For questions not about phabricator.wikimedia.org but about Phabricator in general, go to discourse.phabricator-community.org

█▉▶CUT-99-02

▶🖵 Show last custom slide with license and author information

Thank you for watching!