Making Good PRs
Key Points
- Pull Requests are a way to control the introduction of new content
into a shared repository.
- Pull Requests enable better collaboration for multiple
developers.
- A good PR makes one cohesive change, stays a reasonable size, and
describes what/how/why.
- New PRs can be opened in a repository from a branch or a fork.
- Text on PRs use Markdown styling for formatting.
- A user can interact with PRs in multiple ways: commenting, assigning
reviewers, linking to other issues and pull requests, and more.
- GenAI can draft a PR description from your diff, but only you know
the why — verify it.
- Labelling PRs can help with prioritization and organization.
- PR Templates can provide clear instructions for steps, expectations,
and more.
- GenAI can draft a PR template quickly — adjust it to fit your
team.
- A pull request should contain ONE cohesive change.
- A pull request should, ideally, be quickly reviewable.
- A pull request description should give an overview of what, how, and
why something changed.
- Diagnosing an oversized, unfocused, or undescribed PR is a core
reviewer skill.
- GenAI can assist a review (summaries, first pass) but the human owns
the merge decision.
- Code reviews are integrated into GitHub Pull requests.
- Reviewers can approve, request changes, or simply add comments as
part of the review process.
- Good review comments are kind and specific.
- GenAI can assist a review, but the human owns the merge
decision.
