Abstract Wikipedia team/Definition of Done

A Definition of Done (DoD) is a unified understanding of what should be accomplished before a user story, a task or a product release is considered finished.

A Definition of Done can be applied to different development levels, and those depend on the work cycles of every team. This guide is specifically adapted to the workflow and terminology of the Abstract Wikipedia team. We define three main levels of completion: Phase, milestone or epic, and task.

Phabricator templates

Click on these links to:

• Add a Critical User Journey/Epic
• Add a Design task to Phabricator
• Add a Front-end task
• Add a Front-end bug report
• Add a Back-end task
• Add a Back-end bug report

Template links have been created with this Phabulous tool.

How to use this document

A Definition of Done specification is relevant in two different phases of the development workflow:

1. During phase/epic/task definition: Any item should include a description with the relevant information (list of user stories, detailed user story, detailed bug definition, etc.) and attach an agreed upon checklist with all the criteria that is relevant for this item.
2. During phase/epic/task review and closure: The checklist that was agreed upon phase/epic/task definition should be used to validate the completion of the item.

To write the DoD for a given item, you can follow these steps:

1. Identify the appropriate item level: Are we describing a phase, an epic or milestone of this phase, or a granular task as part of this epic or a bug?
2. Identify the correct channel for writing down the DoD: Should this be written in our project page? Should this be a Phabricator epic or ticket? Will everyone know where to find it?
3. Use the phase/epic/task definition template to write a clear and specific DoD in the right channel.
4. Use the phase/epic/task checklist template to identify which elements should be also considered to validate the completion of the item. Any items that are agreed to be relevant to this phase/epic/task should be copied below the DoD description.

Phase

A development Phase is a collection of user stories (see the Abstract Wikipedia Phase definitions).

Phase definition template

Phase <ID>: <title> User stories: User story description 1, following the format: "As a <user of certain type>, I want to <do this action> so that <the expected result is this one>". User story description 2, etc. Acceptance criteria: Acceptance criteria to add functional details to the user stories detailed above, following a format similar to: "Should be able to <understand this format>" Should be able to <handle this kind of function> Should <disallow unregistered users from performing this action> Should <show a comprehensible message to the user when an error arises> Completion checklist: [x] List of non-functional requirements to complete, copied from the phase completion checklist below, negotiated and filtered to only the requirements that are relevant to this phase [x] E.g. Tests for every project should pass [ ] E.g. Coverage for every project should have improved or stayed the same [ ] E.g. README.md documentation must be updated

Phase completion checklist

• Functionality
  • ☑️ Every user story should be covered by a milestone/epic
  • ☑️ Every child milestone/epic must be marked as complete
  • ☑️ Every phase acceptance criterion must be met
  • ☑️ Tests for every project should pass
  • ☑️ Build process for every project should pass
  • ☑️ Coverage for every project should have improved or stayed the same
  • ☑️ All FIXME annotations should be resolved
  • ☑️ All TODO annotations should have an associated Phabricator task ID
• Design
  • ☑️ Every user story reflected on a user-facing functionality must follow the design system
  • ☑️ Every user story must be reviewed and approved by the design/UX team
• Documentation
  • ☑️ Every user story must be have related and updated documentation
    • Internal technical changes: internal repository documentation must be updated (README.md, JSDoc, PHPDoc)
    • Infrastructure technical changes: technical changes that reflect on environment, infrastructure, endpoints or any other area of interest for technical contributors should be reflected on MediaWiki extension pages.
    • Product or model changes: should have related documentation updated in meta
    • User-facing features: should have an initial user guide draft that will be moved to wikifunctions.org
  • ☑️ Phase completion newsletter must be sent
• Versioning
  • ☑️ All projects must have unified submodule versions
  • ❓ Release version?

Critical User Journey/Epic

A Critical User Journey (CUJ) is described by one Job To Be Done (JTBD) and can involve one or more projects. The JTBD is written from the perspective of the end user/actor/stakeholder, and as such it requires a clear understanding of who this end user is. A JTBD's goal is to clearly understand what the user is trying to achieve, without making strong assumptions about the solution.

The acceptance criteria enriches this narrative by adding functional details to the JTBD, also from the perspective of what the user would expect to accomplish.

CUJ/Epic Phabricator template

• Add a Critical User Journey/Epic to Phabricator

CUJ/Epic definition template

CUJ/Epic <ID>: <title> Job to be done One paragraph describing the situation of the user and what they expect to accomplish, following the format: "When <situation>, I want to <job> so I can <outcome or motivation>". Acceptance criteria A user of some type... Should be able to <handle this kind of function> Should <disallow unregistered users from performing this action> Should <show a comprehensible message to the user when an error arises> Completion checklist [x] List of non-functional requirements to complete [ ] Copy the milestone completion checklist below, negotiate and filter it to only include the requirements that are relevant to this milestone [x] E.g. Tests for every involved project should pass [ ] E.g. Must be reviewed and approved by the design/UX team

CUJ/Epic completion checklist

• Functionality
  • ☑️ Every project involved in the user story should have its associated tasks in Phabricator
  • ☑️ Every related task should pass its DoD checklist
  • ☑️ Tests for every involved project should pass
  • ☑️ Build process for every involved project should pass
  • ☑️ Coverage for every involved project should have improved or stayed the same
• Design
  • ☑️ Design review on updated software
  • ☑️ Test concept via an Alpha, Beta or Prototype with partner communities and those potentially impacted by feature, in their preferred language
• Documentation
  • ☑️ Must be have related and updated documentation
    • Internal technical changes: internal repository documentation must be updated (README.md, JSDoc, PHPDoc)
    • Infrastructure technical changes: technical changes that reflect on environment, infrastructure, endpoints or any other area of interest for technical contributors should be reflected on MediaWiki extension pages.
    • Product or model changes: should have related documentation updated in meta
• Versioning
  • ☑️ If changes in submodule packages are involved, every project that uses this submodule should pass tests and build
• Accessibility
  • ☑️ Implemented features for the CUJ are double checked for compliance with Accessibility guide for developers
    • Unresolved issues are written up in Phabricator tasks and completed

Design

Design task Phabricator template

• Add a Design task to Phabricator

Design task definition template

Design: <title of the critical user journey> Discovery and definition [ ] Goal setting (problem statement, hypotheses) and team-wide presentation [ ] Design brief (goal, user stories, research needed, key user flows) Research and plan [ ] Conduct first round of usability testing with 2–3 variants of design proposals, being sure to center target audiences and measuring impact on accessibility goals and guardrails. Surface possible biases in user testing [ ] Share outcomes of usability testing with internal and external stakeholders Design and develop [ ] High fidelity design proposal with variants [ ] Share design updates (metawiki, newsletter) [ ] Ask for community input (Engineering implementation happens here) Test and iterate [ ] Test concept via an Alpha, Beta or Prototype with partner communities and those potentially impacted by feature, in their preferred language Implement and refine [ ] Design review on updated software

Design task completion checklist

Discovery and definition

• ☑️ Reviewed by PM
• ☑️ Reviewed by Head of Special Projects

Research and plan

• ☑️ Reviewed by PM
• ☑️ Reviewed by Head of Special Projects
• ☑️ Reviewed by the Engineering team (or Workstream Leads)

Design and develop

• ☑️ Compared against the design style guide accessibility principles
• ☑️ Reviewed by Design System team
• ☑️ Reviewed by Head of Special Projects
• ☑️ Reviewed by the Engineering team
  • Designs available on Figma (and links attached to Phabricator tasks)

(Engineering implementation happens here)

Test and iterate

• ☑️ Reviewed by PM
• ☑️ Reviewed by Head of Special Projects

Implement and refine

• ☑️ Reviewed by the Engineering team (or Workstream Leads)

Task/Bug

A task is described by a Phabricator ticket and involves one project only, which should be appropriately tagged in the ticket. Every Phabricator task should follow the AW Phabricator style guide.

Task/Bug Phabricator templates

• Add a Front-end task to Phabricator
• Add a Front-end bug report to Phabricator
• Add a Back-end task to Phabricator
• Add a Back-end bug to Phabricator

Front-end Task/Bug Completion Checklist

• Functionality:
  • ☑️ The solution meets the expected behavior/acceptance criteria described above
  • ☑️ All the child tasks are closed
  • ☑️ The issue has been peer reviewed
  • ☑️ The issue has been merged
• Engineering:
  • ☑️ There are existing and passing unit/integration tests effectively testing its success and its failure
  • ☑️ All new classes/methods are covered by unit tests
  • ☑️ [BUG] Explicit regression test mentioning the bug
• Design:
  • ☑️ Design review of live version in accordance to design standards
• Documentation:
  • ☑️ All new functions/methods are annotated
• Accessibility:
  • ☑️ New functionality is compared against the Accessibility guide for developers
  • ☑️ Accessibility concerns are either address or, if the work is sufficiently large, a new Phabricator ticket is created and linked to this ticket
  • ☑️ All user facing strings are internationalized

Back-end Task/Bug completion checklist

• Functionality:
  • ☑️ The solution meets the expected behavior/acceptance criteria described above
  • ☑️ All the child tasks are closed
  • ☑️ The issue has been peer reviewed
  • ☑️ The issue has been merged
• Engineering:
  • ☑️ There are existing and passing unit/integration tests effectively testing its success and its failure
  • ☑️ All new classes/methods are covered by unit tests
  • ☑️ [BUG] Explicit regression test mentioning the bug
• Documentation
  • ☑️ All new functions/methods are annotated
  • ☑️ Related documentation in MediaWiki extension pages or Abstract Wikipedia pages in meta should be updated with the related changes
    • E.g. New API being created should be reflected in WikiLambda API help page
    • E.g. New error types being added should be reflected in the Representation of errors help page
    • E.g. New keys being added to built-in types should be reflected in the Function model help page
• Versioning
  • ☑️ If changes in submodule packages are involved, every project that uses this submodule should pass tests and build
• Accessibility:
  • ☑️ New functionality is compared against the Accessibility guide for developers
  • ☑️ Accessibility concerns are either address or, if the work is sufficiently large, a new Phabricator ticket is created and linked to this ticket
  • ☑️ All user facing strings are internationalized