Abstract Wikipedia team/Phabricator style guide
Some thoughts about how we want our Phabricator tasks to be written and managed:
Title concerns
[edit]| Tasks … | Guideline | Good and bad examples |
|---|---|---|
| Should be something the team can do; focus on the change. | Titles should start with a verb around the change. | ✔️ Align the function editor design palette to the 2021 Wikimedia standard
❌ The function editor is blue ❌ Happiness in errors |
| Should be something the team can control. | Titles should be scoped to things we can change. | ✔️ Invite people to try out Wikifunctions
❌ Solve the Halting Problem so that our code monitoring always works ❌ Win a Turing award for our work |
| Should be finishable. | Titles should have a completion concept.
(Use a project for endless work.) |
✔️ Launch the Wikifunctions site
❌ Continue to keep the site running |
| Should be easy to understand what it's about.
Should be easy to find tasks and distinguish them. |
Titles should be specific to the change that occurs. | ✔️ Extend the function editor tests to also check it works in RTL interfaces
❌ Fix the thing |
Lifecycle and stakeholder concerns
[edit]| Decisions | Guideline |
|---|---|
| The team uses work board columns on the team board for work scope management. | Tasks should be in the current Quarterly milestone column if they are required work in its scope.
Tasks should be in one of the "Backlog" columns if the team is expecting to need to work on it in the next few Quarters. Tasks should be in the "No current plans" column if that work is not currently planned. |
| The team uses work board columns on the current Quarter for work state management. | All new tasks should come into the Incoming column before being sorted:
When a colleague is looking for their next task, they should generally feel free to take anything from Ready, and move it into In Engineering. When it's ready for design or code review, it should be moved to that column, and then to Ready to deploy. Once a task has been deployed, it should be moved to Ready for Sign-off, and later Resolved by the appropriate owner. |
| The team uses the 'priority' field to schedule work. | Tasks that should be done very soon or now should be tagged High; next up, Medium; later, Low; much later, Lowest. |
| Task state represents reality, it doesn't define it. | Tasks should be in the status and priority that they're going to be worked on by the team. |
| Task acceptance can affect all stakeholders. | Incoming tasks should generally be accepted into the Quarter only in the team's task triage meeting.
Existing tasks should only be de-scoped from the Quarter in the appropriate work planning meeting. Work shouldn't generally start on tasks that we have not yet accepted from "To Triage", except for urgent bugs. |
| Task disposal can affect all stakeholders. | Incoming tasks should generally be declined only in the team task triage meeting.
Existing tasks should only be declined in the task triage meeting. |
| Team members should be able to tell at a glance if a task is something on which they could work. | Task titles should be specific to the change they want to see happen.
Task titles should be short enough they can be easily understood, but not so short that they can't be. Tasks should specify the before and after state desired by the task. |
| Team members should be able to tell for themself if a task is still a concern, and whether they have fixed it. | Tasks should be labelled as feature changes, bugs, or engineering/technical changes.
Definition of done:
|
How to use tags
[edit]| Tag Name | Tag Use | Example |
|---|---|---|
| function-schemata | For tasks that will impact function-schemata code | Create JS classes and builders for ZObjects in function-schemata |
| function-orchestrator | For tasks that will impact function-orchestrator code | Resolve Z18s, Z9s, and Z7s Which Are Not at the Top Level of an Argument |
| function-evaluator | For tasks that will impact function-evaluator code | Use Content-type to Determine How to Parse Evaluator Requests |
| WikiLambda | For tasks that will impact WikiLambda code, including WikiLambda APIs. | Make `ApiFunctionCallTest.php` compare expected vs. received values |
| WikiLambda Front-end | For tasks that will impact Vue components and/or the Vuex store, within the Wikilambda code.
NOTE: this is a subtag of WikiLambda; all tasks that have this tag must also have the WikiLambda tag. |
Integration Tests: Look into factory methods for generating zObjects across production code + tests |
| Abstract Wikipedia Fix-It Tasks | For tasks that are good candidates for team fix-it week, a week every two months dedicated to code cleanup, documentation, and the elimination of tech debt.
NOTE: this tag can be paired with any of the above tags. |
replace existing Tooltip with CODEX version |
| Abstract-Wikipedia-Digital-Garden | For tasks that are in our general brainstorming queue; no direct action is required, but we may continue to revisit them and eventually decide to turn them into executable tasks. | Digital Garden: Given an input(s), an input label(s), and an output generate function name |
| Epic | For tasks that document an epic unit of work; it may have many children tasks | As a member of one of Wikifunction's target communities, I want the outcomes of Wikifunctions to be desirable for me, so that I can benefit from Wikifunctions |
| Design | For tasks that are owned by a designer | Alter the view for instances of user-defined types (fallback UX) |