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.

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.

[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=%2F%2F%3Cerase%20this%20line%3E%20This%20task%20describes%20a%20epic%20or%20milestone%20for%20%5BAW%20or%20Wikifunctions%5D%2F%2F%0D%0A%0D%0A---%0D%0A%0D%0A%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**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%20be%20able%20to%20%5Bunderstand%20some%20format%5D%0D%0A*%20%5B%20%5D%20Should%20%5Bdisallow%20some%20time%20of%20user%20from%20doing%20some%20type%20of%20action%5D%0D%0A%0D%0AAn%20expert%20user...%0D%0A*%20%5B%20%5D%20Should%20be%20able%20to%20%5Bdo%20expert%20things%5D%0D%0A%0D%0A%0D%0A**Involved%20projects%20(repositories)**%0D%0A%0D%0A%2F%2FPlease%20add%20all%20the%20following%20tags%20related%20to%20this%20epic%20to%20the%20%22Tags%22%20field%20%3Cthen%20erase%20this%20section%20from%20the%20description%3E%2F%2F%0D%0A%0D%0A%23function-orchestrator%20%23function-evaluator%20%23function-schemata%20%23wikilambda%20%23abstract_wikipedia_ux%20%0D%0A%0D%0A---%0D%0A%0D%0A%0D%0A%23%23Completion%20checklist%0D%0A%0D%0A%2F%2FDuring%20the%20review%20process%2C%20edit%20and%20check%20these%20items%20to%20reflect%20the%20completion%20status%20of%20this%20epic%2F%2F%0D%0A%0D%0A*%20**Functionality**%0D%0A%20%20*%20%5B%20%5D%20Every%20project%20(repository)%20involved%20in%20this%20user%20story%20has%20its%20separate%20Phabricator%20task%0D%0A%20%20*%20%5B%20%5D%20Every%20related%20task%20should%20passes%20its%20completion%20checklist%0D%0A%20%20*%20%5B%20%5D%20The%20tests%20for%20every%20involved%20project%20pass%20successfully%0D%0A%20%20*%20%5B%20%5D%20The%20build%20process%20for%20every%20involved%20project%20passes%20successfully%0D%0A%20%20*%20%5B%20%5D%20Coverage%20for%20every%20involved%20project%20has%20improved%20or%20stayed%20the%20same%0D%0A*%20**Design**%0D%0A%20%20*%20%5B%20%5D%20Was%20reviewed%20and%20approved%20by%20the%20design%2FUX%20team%0D%0A*%20**Documentation**%0D%0A%20%20*%20%5B%20%5D%20Has%20related%20and%20updated%20documentation%2C%20E.g.%3A%0D%0A%20%20%20%20*%20Internal%20technical%20changes%3A%20internal%20repository%20documentation%20must%20be%20updated%20(README.md%2C%20JSDoc%2C%20PHPDoc)%0D%0A%20%20%20%20*%20Infrastructure%20technical%20changes%3A%20technical%20changes%20that%20reflect%20on%20environment%2C%20infrastructure%2C%20endpoints%20or%20any%20other%20area%20of%20interest%20for%20technical%20contributors%20should%20be%20reflected%20on%20MediaWiki%20extension%20pages.%0D%0A%20%20%20%20*%20Product%20or%20model%20changes%3A%20should%20have%20related%20documentation%20updated%20in%20meta%0D%0A*%20**Versioning**%0D%0A%20%20*%20%5B%20%5D%20If%20changes%20in%20submodule%20packages%20are%20involved%2C%20every%20project%20that%20uses%20this%20submodule%20has%20updated%20submodule%20version%20and%20passes%20tests%20and%20build&projects=Abstract_Wikipedia_team%2C%20Epic Add a Critical User Journey/Epic to Phabricator.]

CUJ/Epic definition template
{| class="wikitable"

CUJ/Epic :
Job to be done

One paragraph describing the situation of the user and what they expect to accomplish, following the format: "When  , I want to   so I can  ".

Acceptance criteria

A user of some type...
 * 1) Should be able to 
 * 2) Should 
 * 3) Should 

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
 * ☑️ Must be reviewed and approved by the design/UX team
 * 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

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 definition template
Legend: 🔧 applicable to task descriptions 🐛 applicable to bug descriptions

Task/Bug completion checklist

 * Functionality
 * ☑️ The issue has been resolved
 * ☑️ 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
 * ☑️ If the task is UX/Design related: it must be reviewed and approved by the UX/Design team
 * Documentation
 * ☑️ All new functions/methods are annotated (JSDoc or PHPDoc)
 * ☑️ 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
 * ❓ Is this necessary for task DoD or should this be an item of Epic/Milestone DoD?