---
id: process.definition-of-done
title: Definition of Done
kind: checklist
domain: process
description: The one checklist that says when a work package may merge - criterion met with a commit and check output, the same gate green locally and in CI, checks seen red first, a verifier who did not build it, and docs, commits and the log in order.
version: 0.1.1
status: review
authority: uask
applies_to: [core]
sources:
  - title: 'Agile Alliance glossary, "Definition of Done"'
    url: https://www.agilealliance.org/glossary/definition-of-done/
    license: LicenseRef-All-Rights-Reserved
    accessed: 2026-11-21
  - title: 'GitHub Docs, "About protected branches" (required status checks and reviews before a merge)'
    url: https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches
    license: CC-BY-4.0
    accessed: 2026-11-21
  - title: 'Google Engineering Practices, "What to look for in a code review"'
    url: https://google.github.io/eng-practices/review/reviewer/looking-for.html
    license: CC-BY-3.0
    accessed: 2026-11-21
requires: [process.work-packages, process.definition-of-ready, quality.quality-release, mgmt.governance-tiers]
related: [config.conventional-commits, req.acceptance-criteria, ops.backups]
templates: [templates/definition-of-done.md]
last_reviewed: 2026-11-21
review_every: 6
---

## Summary

This is the only Definition of Done of the Hub. A work package is done, and may merge, when every line below that applies to it is true; a line that does not apply is
marked "n/a" in the pull request with a reason. "Done" means verified: a commit hash and the output of the checks, otherwise the package is reported as "not verified".
A project copies the list from `templates/definition-of-done.md`, cuts it down to checks it really runs, adds its own lines and removes none that applies at its tier.

## Rules

### Every package

- **R1.** The package MUST meet the Done criterion of its brief, with the evidence in the pull request: a test, a command and its output, or a screenshot
  (`process.work-packages#R7`).
- **R2.** The gate script MUST pass locally and in CI, and it MUST be the same script (`quality.quality-release#R5`, `quality.quality-release#R6`). A failing gate MUST NOT be bypassed
  (`quality.quality-release#R7`).
- **R3.** The checks of the package MUST have been seen to fail before the change and to pass after it; a fixed defect MUST have a regression test at the lowest test level
  that reproduces it (`process.work-packages#R5`, `quality.quality-release#R8`).
- **R4.** At the standard tier and above a verifier who did not build the package MUST have re-run the checks and passed the change (`process.work-packages#R8`,
  `mgmt.governance-tiers#R7`, `mgmt.governance-tiers#R8`); at the lightweight tier the builder MUST have checked the change against this list and said so.
- **R5.** The files changed MUST be those the brief allows; any other MUST be explained in the pull request.
- **R6.** The pull request title and the commits MUST follow Conventional Commits, and a breaking change MUST be marked (`config.conventional-commits#R3`).
- **R7.** The documentation MUST be updated: user documentation, the README, and an ADR when an architecture decision was made. `CHANGELOG.md` MUST have a line under
  Unreleased when users of a release will notice the change.
- **R8.** There MUST be no secrets, no debug leftovers and no new warnings in the build or the logs. A new dependency MUST have a compatible licence, be maintained and have no known
  exploited vulnerability.
- **R9.** A decision that belongs to the owner MUST be listed in the pull request under "Owner decisions needed" and MUST NOT be merged as decided
  (`mgmt.roles-and-decision-rights#R9`).
- **R10.** The package's line MUST be in the project's log: id, branch, commit, verdict and time against the estimate (`process.work-packages#R12`).

### A change to stored data or a live system

- **R11.** A change that can destroy or rewrite data MUST have a backup proved by restore before it, recorded with the change (`ops.backups#R4`, `ops.backups#R5`), and the rollback
  MUST have been tried or its steps listed (`quality.quality-release#R13`).

### The project's own lines

- **R12.** A project MAY add lines for its product, for example an accessibility check of changed pages, a tested down step for a database migration or translations for every changed
  string. It MUST NOT remove a line above that applies at its tier.

## Guidance

Run the list as a person would run a pre-flight check: the author goes down it before asking for a review, the verifier goes down it again with the evidence in hand,
and a missing line is a finding, not a mood. The commonest gap is R3: a check that has never been seen to fail. The next is R1 reported as a sentence ("tested")
instead of a command and its output.

At the lightweight tier R4 is done by the builder against the list. That is a lighter check, not a missing one: the project still says that the list was gone through, and by whom.

The project's own list (a copy of the template) is kept short; a list of thirty lines is read as none. When a defect escapes, change the list (`process.work-packages#R13`) rather
than telling people to be careful.

## Explanation

**Why one list.** "Done" had several homes: a testing line in the project rules, a template, the quality playbook and the pull request template. Each said something a little
different, so a reviewer could not tell which one a pull request was held to. This list is the single home; the others link to it. **Why "verified".** The Agile Alliance describes the Definition of Done as the shared understanding of
what it means for work to be complete. Making that checkable (a command, its output and a hash) keeps the understanding from depending on who is asked.

## Examples

**Good.** WP-2 of a small UK shop: the pull request lists the nine applicable lines with evidence, marks R11 "n/a: the mail template holds no stored data", names commit `3f9a1c2`,
shows the red and then green run of `bash tests/run.sh`, and carries a verifier's pass after one finding was fixed. The log line is written.

**Bad.** A pull request that says "tested, works". There is no hash, no output, the gate was run before the last edit, the verifier is the same session in a new tab, and a dependency was added without a
look at its licence. It is reported as done and merged; three days later the licence turns out to be incompatible.

## Sources

- [Agile Alliance, Definition of Done](https://www.agilealliance.org/glossary/definition-of-done/) — Agile Alliance; the meaning of the term. Accessed 2026-11-21.
- [GitHub Docs, About protected branches](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches) — CC BY 4.0; required status checks and
  reviews before a merge. Accessed 2026-11-21.
- [Google Engineering Practices, What to look for in a code review](https://google.github.io/eng-practices/review/reviewer/looking-for.html) — CC BY 3.0; tests belong with the change and must be able to fail.
  Accessed 2026-11-21.
