Abstract Wikipedia team/Phabricator style guide
Some thoughts about how we want our Phabricator tasks to be written and managed:
| 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 |
| Decisions | Guideline |
|---|---|
| The team uses work board columns on the team board for work scope management. | Tasks should be in a milestone column if they are required work in the scope of that pre-launch phase.
Tasks should be in the "Un-phased" column if the team is unsure as to whether it blocks the launch. Tasks should be in the "Backlog" column if that work is not currently planned. |
| The team uses work board columns on the current phase for work state management. | New tasks should come into the Incoming column.
If the team agrees that the task has a sufficient Definition of Done, it goes into Ready; if not, it goes into Needs Discussion. When a colleague is looking for their next task, they should generally feel free to take anything from Ready, and move it into In Progress. Once a task has been done and any code merged, it should be moved to Ready To Close. |
| 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, priority, and milestone that they're going to be worked on by the team. |
| Task acceptance can affect all stakeholders. | Incoming tasks should generally be accepted from "To Triage" into a phase only in the task triage meeting.
Existing tasks should only be re-scoped from one milestone to another (or into/out of the Backlog) in the task triage 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 much 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:
|
| 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) |