PR quality and best practices — templates, checklists, and the review contract

The pull request is a contract. The author contracts to make a change that does what the description says. The reviewer contracts to read the change and decide whether it is safe to merge. The auditor, six months later, contracts that the merge commit is traceable to a PR that recorded who decided what and why.

The title and the description

The title is the first thing the reviewer reads and the auditor searches for. A title that names the change — feat(login): add v2 login path behind LOGIN_V2 flag — is searchable and self-documenting. A title that does not — fix, WIP, update — is none of those.

gh pr create \
  --title "feat(login): add v2 login path behind LOGIN_V2 flag" \
  --body "$(cat <<'EOF'
## What
Adds the v2 login path. The legacy path remains in place.

## Why
Reduces login latency by 40% (see #456). Hidden behind a flag.

## Side-effects
- Adds the LOGIN_V2 config value with default false.
- Adds a new IAM permission s3:GetObject on the login bucket.
- Requires the login-v2 config toggle to be set in staging.

## Test plan
- terraform plan against staging shows only the expected additions.
- Manual login test against staging with LOGIN_V2=true succeeds.
- tflint and checkov pass.

## Linked issues
- Closes #456.
EOF
)"

The body has a structure. What names the change. Why names the rationale. Side-effects enumerates what else the change touches. Test plan describes what the reviewer can do to verify. Linked issues ties the PR to the tracker.

The PR template

A PR template is a file in the repository — .github/pull_request_template.md on GitHub, .gitlab/merge_request_templates/ on GitLab — pre-populated into the PR description. The template enforces a structure.

## What
## Why
## Side-effects
## Test plan
## Linked issues
## Risk and rollback

## Checklist
- [ ] terraform plan reviewed
- [ ] tflint clean
- [ ] checkov clean
- [ ] Side-effects documented above
- [ ] Linked issue referenced
- [ ] Rollback procedure tested

The checklist is the author’s contract with the reviewer. An unchecked box on a merged PR is the audit trail of a step that was skipped.

The review checklist

The reviewer’s checklist is a separate discipline:

1. Read the title and description first. Does the description match the diff?
2. Read the diff. Is it the size a reviewer can hold in working memory?
3. Check correctness. Does the change do what the description says?
4. Check side-effects. What else does this touch? Are there side-effects the description missed?
5. Check reversibility. Is the change easy to revert?
6. Check the test plan. Can the reviewer execute the plan?
7. Check the linked issues. Is this PR closing an issue that should be closed?

flowchart LR
    A["title + description"] --> B["diff in working memory"]
    B --> C["correctness check"]
    C --> D["side-effects check"]
    D --> E["reversibility check"]
    E --> F["test plan check"]
    F --> G["linked issues check"]
    G --> H["approve or request-changes"]

Production discipline

1. One PR template per repository. Templates vary by team only when the change types vary.
2. Required fields are required. Side-effects, test plan, and linked issues are not optional.
3. The checklist is the audit trail. An unchecked box is a flag.
4. Titles follow a convention. Conventional Commits is a reasonable default; a team-specific convention is fine if documented.
5. Reviewers use the checklist. A reviewer who has not walked through the seven items has not reviewed the PR.

Cross-course references

• GitOps with Argo CD - Part IV (SyncPatterns): how PR quality interacts with the GitOps reconciliation.
• CI/CD Pipeline Patterns - Part VIII (ApprovalGates): the PR template’s role in the approval gate.
• Terraform for Production Sysadmins - Part XI (PRWorkflows): the Terraform-specific PR template.

Quiz