Opening and describing a PR
You wrote the change, ran the tests, and the diff looks clean. Now you need to open a PR — but a one-line title like "fix bug" leaves the reviewer with nothing to start from. A good PR description doesn't repeat what the diff already shows — it explains the why: what triggered the change, how to ver
A good description is like a note you leave for a babysitter: writing 'watch the kid' isn't enough — you need to explain why tonight's routine is different and how to check everything's fine before bed.
- PR description
- The text accompanying a Pull Request that explains to the reviewer why the change was made, how to test it, and what the risk is — not just a restatement of what the diff already shows.
- PR template
- A standing file in the repo (e.g. .github/pull_request_template.md) that fixes which sections must appear in every PR description, so everyone fills in the same information.
- draft PR
- A PR opened in draft state — visible to the team and runs checks, but doesn't signal 'ready for full review' until it's marked Ready for review.
- ready for review
- The action that turns a draft PR into a state that actively asks for a reviewer's full attention — the signal that the work is ready, not just visible.
