DEV Community

Cover image for A Definition of Done That Devs and QA Both Believe
ProjTL
ProjTL

Posted on

A Definition of Done That Devs and QA Both Believe

Every team has had this exact conversation.

A developer says the ticket is done. QA opens it and finds the happy path works, but the error state is blank, the API returns a 500 on empty input, and nobody wrote down how to test it.

Nobody lied. The developer meant "the code is merged". QA meant "I can sign this off". The product owner meant "a customer can use it". Three people, three definitions, one ticket stuck in a loop.

A definition of done (DoD) fixes that. This post walks through how to write one that both developers and QA will actually follow, rather than one that sits in a wiki.

What a definition of done is (and isn't)

A DoD is a short checklist that every item must pass before anyone calls it finished. It applies to all work, which makes it different from acceptance criteria.

  • Acceptance criteria are specific to one story: "a user can reset their password using the emailed link".
  • Definition of done is the shared bar for every story: "tested, reviewed, documented, deployable".

Think of acceptance criteria as what was asked for, and the DoD as how well it has to be finished.

Why most DoDs fail

Before writing yours, it helps to see why the usual ones do not work.

They are too long. A 25-line checklist gets ticked without reading. If people tick boxes they did not check, the list is worse than having none.

They are written by one role. A DoD written only by developers skips the questions QA actually asks. One written only by QA reads like a gate that developers have to get past.

They are vague. "Code is tested" can mean anything from "I ran it once" to "full coverage with edge cases".

Nobody owns it. If no one can say who checks each line, nobody does.

Write it together, in one short sitting

Get a developer, a tester and whoever owns the product in the same room for 45 minutes. Ask one question: "What has gone wrong after we called something done?"

Pull three or four real examples from recent sprints. Maybe a bug that escaped because no one tested an empty state, or a feature that shipped without a migration. Each example usually turns into one checklist line.

Aim for six to eight items. If you go beyond ten, cut something.

A starting checklist

Here is a template you can adapt. Every line is something a person can answer with a clear yes or no.

## Definition of Done

### Code
- [ ] Merged to the main branch via an approved pull request
- [ ] No new linter or type-check errors

### Testing
- [ ] Acceptance criteria verified by someone other than the author
- [ ] Error, empty and boundary states checked
- [ ] Automated tests added or updated for the change
- [ ] No open bugs with severity "blocker" or "critical" linked to this work

### Release
- [ ] Deployed to the test environment and checked there
- [ ] Config, migrations and feature flags documented
- [ ] Notes added for support or the next developer
Enter fullscreen mode Exit fullscreen mode

Notice how specific each line is. "Verified by someone other than the author" can be checked. "Well tested" cannot.

A worked example

Take a story: "Users can export their task list as CSV."

The developer finishes the export button and the file downloads. Under a vague definition, that is done. Under the checklist above, the conversation looks different:

DoD line What it surfaces
Error, empty and boundary states checked What does the file contain when the list is empty? What about 50,000 rows?
Verified by someone other than the author QA finds that commas in task names break the columns
Automated tests added or updated A test for quoted fields and special characters now exists
Notes for support The file uses UTF-8, so a note explains opening it correctly in a spreadsheet

Same story, but four problems caught before release instead of after.

Making it stick

A checklist is only useful if it is part of the daily flow.

  1. Put it where the work is. Add it to your pull request template and your ticket template, not a separate page nobody opens.
  2. Give each line an owner. Developers tick the code lines. QA ticks the testing lines. It is clear who is accountable.
  3. Review it every few sprints. After a bug escapes, ask whether a DoD line would have caught it. If yes, add one. If a line never catches anything, remove it.
  4. Keep it honest. If you cannot meet the DoD for a story, say so and agree an exception openly. Quietly skipping it teaches everyone to ignore it.

A small pull request template can do much of this for you:

## What changed
<!-- one or two sentences -->

## How to test
<!-- steps, including empty and error states -->

## Definition of done
- [ ] Reviewed and approved
- [ ] Tests added or updated
- [ ] Verified by someone other than me
- [ ] Notes added for support or the next dev
Enter fullscreen mode Exit fullscreen mode

Common traps

  • Using DoD as a stick. It should help the team agree what finished means. If it feels like a gate someone else controls, it will be resented.
  • Confusing it with "ready". A definition of ready describes when a story is clear enough to start. A DoD describes when it is finished. You may need both, but they solve different problems.
  • Growing it after every incident. Not every bug needs a new rule. Add a line only when the same kind of problem has happened more than once.

The takeaway

"Done" is a shared agreement, not a feeling. A short checklist that developers and QA wrote together, tied to real problems your team has hit, removes the quiet disagreement about what finished means.

Try it for one sprint. Count how many tickets bounce back from QA before and after. If the number drops, keep the list. If not, find the line that is missing.

What is on your team's definition of done? I would love to see what others include.

Top comments (0)