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: Template links have been created with this Phabulous tool.
 * [https://phabricator.wikimedia.org/maniphest/task/edit/form/1/?title=%3CCUJ%20n%3E%20or%20%3CEpic%20n%3E%3A%20%3CTitle%20of%20the%20Core%20User%20Journey%20or%20Epic%3E&description=%23%23%20%3CCritical%20User%20Journey%20n%3E%20or%20%3CEpic%20n%3E%3A%20%3CTitle%20of%20the%20CUJ%20or%20Epic%3E%0D%0A%0D%0A%0D%0A**Job%20To%20Be%20Done**%0D%0A%0D%0A%2F%2F%3Cerase%20this%20line%3E%20Include%20a%20brief%20description%20of%20the%20user%20story%20in%20the%20format%20of%20a%20JTBD%3A%2F%2F%0D%0A%0D%0AWhen%20%3Csituation%3E%20I%20want%20to%20%3Cjob%3E%20so%20I%20can%20%3Cexpected%20outcome%20or%20motivation%3E%0D%0A%0D%0A%0D%0A**Acceptance%20criteria**%0D%0A%0D%0A%2F%2F%3Cerase%20this%20line%3E%20Include%20a%20list%20of%20functional%20details%20that%20expand%20the%20JTBD%20detailed%20above%2C%20following%20a%20format%20similar%20to%3A%2F%2F%0D%0A%0D%0AA%20normal%20user...%0D%0A*%20%5B%20%5D%20Should%20...%0D%0A*%20%5B%20%5D%20...%0D%0A%0D%0AAn%20expert%20user...%0D%0A*%20%5B%20%5D%20...%0D%0A%0D%0A---%0D%0A%0D%0A**Remove%20all%20the%20non-applicable%20tags%20from%20the%20%22Tags%22%20field%2C%20leave%20only%20the%20tags%20of%20the%20projects%2Frepositories%20related%20to%20this%20task**%0D%0A%0D%0A---%0D%0A%0D%0A%0D%0A%0D%0A%23%23%20Completion%20checklist%0D%0A%0D%0A*%20%5B%20%5D%20Before%20closing%20this%20Epic%2C%20review%20one%20by%20one%20the%20checklist%20available%20here%3A%20https%3A%2F%2Fwww.mediawiki.org%2Fwiki%2FAbstract_Wikipedia_team%2FDefinition_of_Done%23CUJ%2FEpic_completion_checklist&projects=Abstract_Wikipedia_team%2C%20function-orchestrator%2C%20function-evaluator%2C%20function-schemata%2C%20wikilambda%2C%20abstract_wikipedia_ux Add a Critical User Journey/Epic]
 * [https://phabricator.wikimedia.org/maniphest/task/edit/form/1/?title=Design%3A%20%3Ctitle%20of%20the%20critical%20user%20journey%3E&description=**Discovery%20and%20definition**%0D%0A-%20%5B%20%5D%20Goal%20setting%20(problem%20statement%2C%20hypotheses)%20and%20team-wide%20presentation%0D%0A-%20%5B%20%5D%20Design%20brief%20(goal%2C%20user%20stories%2C%20research%20needed%2C%20key%20user%20flows)%0D%0A%0D%0A**Research%20and%20plan**%0D%0A-%20%5B%20%5D%20Conduct%20first%20round%20of%20usability%20testing%20with%202%E2%80%933%20variants%20of%20design%20proposals%2C%20being%20sure%20to%20center%20target%20audiences%20and%20measuring%20impact%20on%20accessibility%20goals%20and%20guardrails.%20Surface%20possible%20biases%20in%20user%20testing%0D%0A-%20%5B%20%5D%20Share%20outcomes%20of%20usability%20testing%20with%20internal%20and%20external%20stakeholders%0D%0A%0D%0A**Design%20and%20develop**%0D%0A-%20%5B%20%5D%20High%20fidelity%20design%20proposal%20with%20variants%0D%0A-%20%5B%20%5D%20Share%20design%20updates%20(metawiki%2C%20newsletter)%0D%0A-%20%5B%20%5D%20Ask%20for%20community%20input%0D%0A%0D%0A%2F%2F(Engineering%20implementation%20happens%20here)%2F%2F%0D%0A%0D%0A**Test%20and%20iterate**%0D%0A-%20%5B%20%5D%20Test%20concept%20via%20an%20Alpha%2C%20Beta%20or%20Prototype%20with%20partner%20communities%20and%20those%20potentially%20impacted%20by%20feature%2C%20in%20their%20preferred%20language%0D%0A%0D%0A**Implement%20and%20refine**%0D%0A-%20%5B%20%5D%20Design%20review%20on%20updated%20software%0D%0A%0D%0A**Completion%20checklist**%0D%0ABefore%20closing%20this%20task%2C%20review%20one%20by%20one%20the%20checklist%20available%20here%3A%20https%3A%2F%2Fwww.mediawiki.org%2Fwiki%2FAbstract_Wikipedia_team%2FDefinition_of_Done%23Design_task_completion_checklist&projects=Abstract_Wikipedia_team%2C%20design Add a Design task to Phabricator]
 * Add a Front-end task
 * Add a Front-end bug report
 * Add a Back-end task
 * [https://phabricator.wikimedia.org/maniphest/task/edit/form/43/?title=%3CShort%20one-liner%20describing%20the%20problem%3E&description=%23%23%20Description%0D%0A%0D%0A**Steps%20to%20reproduce%20(step%20by%20step%20instructions%2C%20with%20links%2C%20commands%20and%20necessary%20data%20to%20reproduce%20the%20error)**%0D%0A%0D%0A%20%20%23%20E.g.%20run%20some%20test%20with%20the%20command%20%60npm%20run%20test%3Anolint%20--%20-t%20%22some%20test%20called%20some%20name%22%60%0D%0A%20%20%23%20E.g.%20send%20a%20request%20to%20the%20following%20API%20https%3A%2F%2Fsandbox.api.full.link%20with%20the%20following%20load%3A%20%60%7B%20%22Z1K1%22%3A%20%22Z7%22%2C%20%22Z7K1%22%3A%20%22Z100000%22%20%7D%60%0D%0A%0D%0A**Observed%20behavior**%0D%0A%0D%0A*%20...%0D%0A%0D%0A**Expected%20behavior%2FAcceptance%20criteria%20(returned%20value%2C%20expected%20error%2C%20performance%20expectations%2C%20etc.)**%0D%0A%0D%0A*%20...%0D%0A%0D%0A---%0D%0A%0D%0A**Remove%20all%20the%20non-applicable%20tags%20from%20the%20%22Tags%22%20field%2C%20leave%20only%20the%20tags%20of%20the%20projects%2Frepositories%20related%20to%20this%20task**%0D%0A%0D%0A---%0D%0A%0D%0A%23%23%20Completion%20checklist%0D%0A%0D%0A*%20%5B%20%5D%20Before%20closing%20this%20task%2C%20review%20one%20by%20one%20the%20checklist%20available%20here%3A%20https%3A%2F%2Fwww.mediawiki.org%2Fwiki%2FAbstract_Wikipedia_team%2FDefinition_of_Done%23Back-end_Task%2FBug_completion_checklist&projects=Abstract_Wikipedia_team%2C%20function-orchestrator%2C%20function-evaluator%2C%20function-schemata%2C%20wikilambda Add a Back-end bug report]

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 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  annotations should be resolved
 * ☑️ All  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

 * [https://phabricator.wikimedia.org/maniphest/task/edit/form/1/?title=%3CCUJ%20n%3E%20or%20%3CEpic%20n%3E%3A%20%3CTitle%20of%20the%20Core%20User%20Journey%20or%20Epic%3E&description=%23%23%20%3CCritical%20User%20Journey%20n%3E%20or%20%3CEpic%20n%3E%3A%20%3CTitle%20of%20the%20CUJ%20or%20Epic%3E%0D%0A%0D%0A%0D%0A**Job%20To%20Be%20Done**%0D%0A%0D%0A%2F%2F%3Cerase%20this%20line%3E%20Include%20a%20brief%20description%20of%20the%20user%20story%20in%20the%20format%20of%20a%20JTBD%3A%2F%2F%0D%0A%0D%0AWhen%20%3Csituation%3E%20I%20want%20to%20%3Cjob%3E%20so%20I%20can%20%3Cexpected%20outcome%20or%20motivation%3E%0D%0A%0D%0A%0D%0A**Acceptance%20criteria**%0D%0A%0D%0A%2F%2F%3Cerase%20this%20line%3E%20Include%20a%20list%20of%20functional%20details%20that%20expand%20the%20JTBD%20detailed%20above%2C%20following%20a%20format%20similar%20to%3A%2F%2F%0D%0A%0D%0AA%20normal%20user...%0D%0A*%20%5B%20%5D%20Should%20...%0D%0A*%20%5B%20%5D%20...%0D%0A%0D%0AAn%20expert%20user...%0D%0A*%20%5B%20%5D%20...%0D%0A%0D%0A---%0D%0A%0D%0A**Remove%20all%20the%20non-applicable%20tags%20from%20the%20%22Tags%22%20field%2C%20leave%20only%20the%20tags%20of%20the%20projects%2Frepositories%20related%20to%20this%20task**%0D%0A%0D%0A---%0D%0A%0D%0A%0D%0A%0D%0A%23%23%20Completion%20checklist%0D%0A%0D%0A*%20%5B%20%5D%20Before%20closing%20this%20Epic%2C%20review%20one%20by%20one%20the%20checklist%20available%20here%3A%20https%3A%2F%2Fwww.mediawiki.org%2Fwiki%2FAbstract_Wikipedia_team%2FDefinition_of_Done%23CUJ%2FEpic_completion_checklist&projects=Abstract_Wikipedia_team%2C%20function-orchestrator%2C%20function-evaluator%2C%20function-schemata%2C%20wikilambda%2C%20abstract_wikipedia_ux Add a Critical User Journey/Epic to Phabricator]

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 task Phabricator template

 * [https://phabricator.wikimedia.org/maniphest/task/edit/form/1/?title=Design%3A%20%3Ctitle%20of%20the%20critical%20user%20journey%3E&description=**Discovery%20and%20definition**%0D%0A-%20%5B%20%5D%20Goal%20setting%20(problem%20statement%2C%20hypotheses)%20and%20team-wide%20presentation%0D%0A-%20%5B%20%5D%20Design%20brief%20(goal%2C%20user%20stories%2C%20research%20needed%2C%20key%20user%20flows)%0D%0A%0D%0A**Research%20and%20plan**%0D%0A-%20%5B%20%5D%20Conduct%20first%20round%20of%20usability%20testing%20with%202%E2%80%933%20variants%20of%20design%20proposals%2C%20being%20sure%20to%20center%20target%20audiences%20and%20measuring%20impact%20on%20accessibility%20goals%20and%20guardrails.%20Surface%20possible%20biases%20in%20user%20testing%0D%0A-%20%5B%20%5D%20Share%20outcomes%20of%20usability%20testing%20with%20internal%20and%20external%20stakeholders%0D%0A%0D%0A**Design%20and%20develop**%0D%0A-%20%5B%20%5D%20High%20fidelity%20design%20proposal%20with%20variants%0D%0A-%20%5B%20%5D%20Share%20design%20updates%20(metawiki%2C%20newsletter)%0D%0A-%20%5B%20%5D%20Ask%20for%20community%20input%0D%0A%0D%0A%2F%2F(Engineering%20implementation%20happens%20here)%2F%2F%0D%0A%0D%0A**Test%20and%20iterate**%0D%0A-%20%5B%20%5D%20Test%20concept%20via%20an%20Alpha%2C%20Beta%20or%20Prototype%20with%20partner%20communities%20and%20those%20potentially%20impacted%20by%20feature%2C%20in%20their%20preferred%20language%0D%0A%0D%0A**Implement%20and%20refine**%0D%0A-%20%5B%20%5D%20Design%20review%20on%20updated%20software%0D%0A%0D%0A**Completion%20checklist**%0D%0ABefore%20closing%20this%20task%2C%20review%20one%20by%20one%20the%20checklist%20available%20here%3A%20https%3A%2F%2Fwww.mediawiki.org%2Fwiki%2FAbstract_Wikipedia_team%2FDefinition_of_Done%23Design_task_completion_checklist&projects=Abstract_Wikipedia_team%2C%20design Add a Design task to Phabricator]

Design task completion checklist
Discovery and definition Research and plan Design and develop
 * ☑️ Reviewed by PM
 * ☑️ Reviewed by Head of Special Projects
 * ☑️ Reviewed by PM
 * ☑️ Reviewed by Head of Special Projects
 * ☑️ Reviewed by the Engineering team (or Workstream Leads)
 * ☑️ Compared against the design style guide accessibility principles
 * ☑️ Reviewed by Design System team
 * ☑️ 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
 * [https://phabricator.wikimedia.org/maniphest/task/edit/form/43/?title=%3CShort%20one-liner%20describing%20the%20problem%3E&description=%23%23%20Description%0D%0A%0D%0A**Steps%20to%20reproduce%20(step%20by%20step%20instructions%2C%20with%20links%2C%20commands%20and%20necessary%20data%20to%20reproduce%20the%20error)**%0D%0A%0D%0A%20%20%23%20E.g.%20run%20some%20test%20with%20the%20command%20%60npm%20run%20test%3Anolint%20--%20-t%20%22some%20test%20called%20some%20name%22%60%0D%0A%20%20%23%20E.g.%20send%20a%20request%20to%20the%20following%20API%20https%3A%2F%2Fsandbox.api.full.link%20with%20the%20following%20load%3A%20%60%7B%20%22Z1K1%22%3A%20%22Z7%22%2C%20%22Z7K1%22%3A%20%22Z100000%22%20%7D%60%0D%0A%0D%0A**Observed%20behavior**%0D%0A%0D%0A*%20...%0D%0A%0D%0A**Expected%20behavior%2FAcceptance%20criteria%20(returned%20value%2C%20expected%20error%2C%20performance%20expectations%2C%20etc.)**%0D%0A%0D%0A*%20...%0D%0A%0D%0A---%0D%0A%0D%0A**Remove%20all%20the%20non-applicable%20tags%20from%20the%20%22Tags%22%20field%2C%20leave%20only%20the%20tags%20of%20the%20projects%2Frepositories%20related%20to%20this%20task**%0D%0A%0D%0A---%0D%0A%0D%0A%23%23%20Completion%20checklist%0D%0A%0D%0A*%20%5B%20%5D%20Before%20closing%20this%20task%2C%20review%20one%20by%20one%20the%20checklist%20available%20here%3A%20https%3A%2F%2Fwww.mediawiki.org%2Fwiki%2FAbstract_Wikipedia_team%2FDefinition_of_Done%23Back-end_Task%2FBug_completion_checklist&projects=Abstract_Wikipedia_team%2C%20function-orchestrator%2C%20function-evaluator%2C%20function-schemata%2C%20wikilambda 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