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 definition template
{| class="wikitable"

Phase :
User stories:
 * 1) User story description 1, following the format: "As a  , I want to   so that ".
 * 2) User story description 2, etc.

Acceptance criteria:
 * 1) Acceptance criteria to add functional details to the user stories detailed above, following a format similar to: "Should be able to  "
 * 2) Should be able to 
 * 3) Should 
 * }

Phase completion checklist

 * Functionality
 * ☑️ Every user story should be covered by a milestone/epic
 * ☑️ Every phase milestone/epic should pass their DoD checklist
 * ☑️ 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?

Milestone/Epic
A milestone is described by one user story and can involve one or more projects.

Milestone/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 completion checklist

 * Functionality
 * ☑️ The issue detailed in the Phabricator ticket description is solved
 * ☑️ All the child tasks are closed
 * ☑️ There are existing and passing unit/integration tests effectively testing its success and its failure
 * ☑️ The issue has been peer reviewed
 * ☑️ The issue has been merged
 * 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?