Skip to content

PR Template — Reference Content

This is the content of the GitHub Pull Request template that should live at .github/PULL_REQUEST_TEMPLATE.md once the team is able to push to the repo. Until then, this doc serves as the canonical reference and can be copy-pasted into the actual file when the time comes.

For the rationale of each checklist item, see Definition of Done. For the principles being enforced, see Engineering Charter. For the full practice catalog, see Engineering Practices.

How to install (when ready)

When write access is available:

mkdir -p .github
# Copy the content below (between the markers) into .github/PULL_REQUEST_TEMPLATE.md

GitHub auto-detects this file and prefills every new PR with its content. Engineers can edit / tick boxes / fill the description section before opening the PR.

Optional: multiple templates can be configured by placing files in .github/PULL_REQUEST_TEMPLATE/ directory (e.g., feature.md, hotfix.md, chore.md). For most teams, one template is enough.

Template content

Everything between the two markers below is the template body. Copy from <!-- TEMPLATE START --> to <!-- TEMPLATE END -->.

<!-- TEMPLATE START -->

## What this PR does

<!-- 1-3 sentences. What's changing and why. -->



## How to verify

<!-- Steps to reproduce or test the change. Include URLs, queries, or commands a reviewer can run. -->



## Type of change

<!-- Tick exactly one. -->

- [ ] `feat:` New feature
- [ ] `fix:` Bug fix
- [ ] `refactor:` Refactor without behavior change
- [ ] `perf:` Performance improvement
- [ ] `test:` Tests only
- [ ] `docs:` Documentation only
- [ ] `chore:` Tooling, config, dependencies
- [ ] `ci:` CI/CD changes
- [ ] `build:` Build system or dependencies
- [ ] `style:` Formatting only

## Definition of Done

<!--
Tick each item that applies. Mark `n/a` (in the description) for items that don't.
Each item is explained in doc/definition-of-done.md.
-->

- [ ] Code passes lint, typecheck, and tests locally
- [ ] New code has tests for the happy path and at least one error case
- [ ] No `console.log`, no `any`, no `@ts-ignore` — or each has a justified `// @ts-expect-error: <reason>`
- [ ] No new secrets committed; gitleaks pre-commit passed
- [ ] If endpoint added or changed: OpenAPI spec updated in this PR
- [ ] If schema changed: migration file added in `migrations/`
- [ ] If new env var: added to `.env.example` and `configuration.md`
- [ ] If new external dependency: justified below; license / size / maintenance checked
- [ ] If touching a legacy file (`routes/routes.js`, `routes/auth.js`): boy-scout improvement described below
- [ ] If new endpoint: rate limit + auth role declared
- [ ] If new background job: idempotent, uses queue (not polling)
- [ ] CI is green
- [ ] Self-review: I read the diff before requesting review

## New dependency justification

<!-- Skip if no new package added. Otherwise: what / why / alternatives / license / size / last release. -->



## Boy-scout improvement

<!-- Skip if no legacy-file touch. Otherwise: what did you upgrade as part of this change? -->



## Exceptions

<!--
Skip if you complied with all applicable rules. Otherwise list each:
- Practice / rule referenced
- Reason for the exception
- Follow-up issue or plan
Exceptions are reviewed by an engineering lead, not just any reviewer.
-->



## Related issues / PRs

<!-- Linear / Jira / GitHub issue links. "Closes #123" or "Relates to #456". -->



<!-- TEMPLATE END -->

Notes for the team

What "tick the box" means

A ticked box is a personal commitment that the item is actually done, not a checklist of things you intended to do. A reviewer who finds an unticked item or a falsely-ticked box may reject the PR; persistent issues with this become a tier-3 (cultural) discussion.

Items marked n/a

Some items don't apply to every PR. A doc-only PR doesn't need new tests; a deletion PR doesn't need an OpenAPI update. Mark these n/a in the description rather than ticking them as done. The pattern:

## Definition of Done

- [x] Code passes lint, typecheck, and tests locally
- [x] No `console.log`, no `any`, no `@ts-ignore`
- [x] No new secrets committed
- [n/a] New code has tests — *doc-only PR*
- [n/a] OpenAPI spec — *no API changes*
- [n/a] Schema migration — *no schema changes*
...

This makes the inapplicable items visible without misrepresenting completion.

Self-review

Before clicking "request review," open the "Files Changed" tab and read your diff. About half of all PR feedback is preventable by the author re-reading their own change.

Hot-fix exemption

Production-down emergencies may use a stripped-down template (separate file hotfix.md once installed) with only the critical items. Engineering-lead approval is required, and a follow-up PR addresses anything skipped.

When this file should be installed

The template should land at .github/PULL_REQUEST_TEMPLATE.md no later than Wave 1 of the practices-adoption schedule (week 1). It's foundational — branch protection, CODEOWNERS, and pre-commit hooks all assume it's in place.

Until it's installed, this reference doc serves the same purpose: engineers manually paste the template content into the PR description. It's clunkier but functional.

Variations worth considering later

For mature teams, the single template above can be split into multiple templates:

  • .github/PULL_REQUEST_TEMPLATE/feature.md — full Definition of Done
  • .github/PULL_REQUEST_TEMPLATE/hotfix.md — abbreviated, requires lead approval
  • .github/PULL_REQUEST_TEMPLATE/chore.md — for routine maintenance
  • .github/PULL_REQUEST_TEMPLATE/docs.md — for doc-only changes

GitHub picks based on the URL parameter ?template=<name> or shows a chooser. Recommended only after the single-template approach has been used for a few months and the team has data on which patterns are common.