Why the PR title matters
The PR title is what reviewers see in their list, what shows up in notifications and -if you use squash merge- what ends up as the commit message on main. A good title saves clicks (you don't need to open the PR to know what it's about) and makes searching six months later easy.
Recommended structure
<type>(<scope>): <imperative verb> <what changes>.
Examples: feat(auth): add password reset flow,
fix(api): handle null response from upstream,
refactor(billing): extract invoice generator into service.
Imperative verbs
"Add", "fix", "refactor", "remove", "update", "improve", "rename", "extract", "bump". The gerund ("adding") and past tense ("added") are less direct. The mnemonic works for PR titles too: "If applied, this PR will add password reset flow".
What to avoid
- "Misc fixes" or "Update stuff": tell you nothing.
- Titles with just the ticket number:
PROJ-123with no description. - WIP in the title once it's ready for review.
- Leading emojis if your repo uses squash merge: break parsing tools.
- More than 72 characters: gets truncated in many views.
Squash merge and commit message
With squash merge, the PR title becomes the commit message on main. If you follow Conventional Commits in titles, semantic-release can build changelogs automatically. With merge commit, the original commits are preserved and the PR title is just metadata.
The PR body
The title says what; the body says why. Typical template: What (one-line summary), Why (motivation), How (technical decisions), Testing (how you verified), Screenshots (when relevant), Related (links to issues, docs).
Tickets and references
If your system has magic words (Closes #123, Fixes JIRA-456),
put them in the body, not the title. GitHub and GitLab close issues automatically on
merge. Exception: include the ticket ID in the title if your repo policy requires it.
Big PRs vs small PRs
If the title doesn't fit in 72 characters, the PR is probably too large. Split it into smaller PRs with specific titles. Reviews of huge PRs are shallow and slow the team. Sensible target: PRs reviewable in 15 minutes or less.