A Pull Request Template Reviewers Actually Read

A pull request description is for the reviewer, and later for the person who has to understand the change from git history. It is not a form you satisfy. The failure mode of most templates is that they are long, so authors leave the placeholder text in place and request review anyway.

Reviewers read the first few lines and then the diff. Give them the problem, the part of the diff that matters, and how you know it works. If a section would be empty, delete it.

What the description has to answer

• Why this change exists. A link to a ticket is not a substitute. The ticket is context. The description is the argument.
• Where to look. On a change that touches many files, say which path carries the real decision, and which files are mechanical.
• How you checked it. A command, a click-path, or the test that fails without the fix.
• What you left out on purpose, so the reviewer does not spend ten minutes hunting for a case you deferred.

The template

Save this as .github/pull_request_template.md. GitHub fills it in when someone opens a pull request. That is the whole setup.

## Why
The problem this change exists to solve, in one or two sentences.
Link the issue if there is one. The link does not replace the sentences.

## What to look at
- The path that carries the real change
- Anything easy to miss: a migration, a default, a permission

## How I checked it
The command, the click-path, or the test that fails without this change.

## Left out
What this pull request does not do, on purpose.

A filled-in example

Same change, written for a person. Notice it names the failure and the file.

## Why
A deploy overlapped the cron window and the nightly billing job ran on
both app servers. Some customers were charged twice. This makes the
job take a Postgres advisory lock and exit if another copy holds it.

Fixes #482.

## What to look at
- app/Jobs/NightlyBilling.php, the lock and the early return
- The new test. The migration is empty on purpose.

## How I checked it
The test fails if the lock call is removed. I also started two
copies locally; the second logged "already running" and exited 0.

## Left out
No alert if the job skips. It runs again the next night, which is
fine until billing needs to be same-day.

Why the long templates fail

A template with eleven checkboxes trains people to tick them. "Tests added," "docs updated," "no breaking changes," all still checked on a pull request that has none of those things. The boxes become scenery. Reviewers learn to ignore the description, and then authors learn that writing one is pointless, which is the whole system failing at once.

Keep the template shorter than the description you hope to get. If the placeholder text is still in the box when you click ready for review, you have not written a description. Delete the headings you did not use.