Checklist · Stacks and tools
Pull Request Checklist: Before You Open a PR
Opens with creditsA checklist to go through before you open or mark a pull request ready for review. It is built on Google's published guidance for authors and GitHub's pull request documentation, and each check says how much it matters and exactly how to confirm it, from the size of the change to tests, the description, release safety and responding to review.
Written by Tauseef Fayyaz8 chapters, 37 checksAbout 19 minReviewed 13 October 2026What you will learn
8 chapters · about 19 min
1Scope and sizeSmall, focused pull requests are reviewed faster and more carefully. These checks make sure the change does one thing and is a size a reviewer can handle.4 checks · 2 min
2Code is ready for other eyesThese checks make sure the reviewer sees finished code that builds, passes the automated checks and contains nothing you would not want merged.5 checks · 3 min
- 1The project builds and the lint, format and type checks pass locally
- 2No debug logs, commented out code or stray TODOs are left in
- 3No secrets, credentials or personal data are in the diff
- 4Any dependency change is intentional, explained and has its lock file
- 5New failure paths are handled and logged usefully
5 in this chapterOpen this chapter- TestsGoogle's guidance says logic changes should come with new or updated tests in the same change. These checks make sure the tests exist, prove something and do not quietly skip anything.4 checks · 2 minOpens with credits
- Self reviewGitHub recommends reviewing your own pull request before anyone else does. These checks are what to look for when you read your own diff.4 checks · 2 minOpens with credits
- Title and descriptionThe description is the reviewer's starting point and the permanent record of why the change exists. These checks make it do both jobs.6 checks · 3 minOpens with credits
- Release safetySome changes are risky not because the code is wrong but because of how they reach production. These checks cover migrations, breaking changes, configuration and documentation.5 checks · 3 minOpens with credits
- Branch, commits and requesting reviewThe last checks before you hit the button: a branch that is current, commits that make sense, green CI and the right reviewers.5 checks · 2 minOpens with credits
- During reviewThe checklist does not end when you request review. These checks keep the conversation moving and the result clean.4 checks · 2 minOpens with credits
About this checklist
This pull request checklist is what you run through in the ten minutes before you ask someone to review your code. It is built on Google's engineering practices for change authors, GitHub's own guidance on pull requests, the Git documentation and the Conventional Commits specification.
A reviewer's time is the most expensive part of a pull request. Every leftover debug line, missing test, unexplained file or vague description costs a round trip, and each round trip can cost a day. Most of those are things you can catch yourself in a few minutes, before anyone else looks.
Every check has a severity. A must is something that will block the review or put users at risk if you skip it. A should is something reviewers will reasonably expect. A nice makes the review faster or the history more useful. Every check also says how to verify it: a command to run, a place in the diff to look, a field in the description to fill in.
The chapters follow the order you work in: scope the change, clean up the code, check the tests, review your own diff, write the description, think about the release, tidy the branch, and finally handle the review itself.
Common questions
What should I check before opening a pull request?
Check that the change does one thing and is a reviewable size, that it builds and passes lint, types and tests locally, and that there are no debug leftovers, secrets or unrelated files. Read your own diff on the pull request page, then write a specific title and a description that says what changed, why and how you tested it.
How big should a pull request be?
Google's guidance says about 100 lines is usually reasonable and about 1,000 lines is usually too large, with file spread mattering too. What matters most is that the pull request does one self contained thing and includes its tests. Split big work by layer or put refactors in their own pull request.
What should a pull request description include?
What the change does, why it is needed and how you tested it. Link the related issue, add screenshots for UI changes, call out risks such as migrations or breaking changes, and on larger changes say which file to start with. Keep the key context in the description, not only in a linked ticket.
How do I automatically close an issue when a pull request merges?
Put a closing keyword such as Fixes #123, Closes #123 or Resolves #123 in the pull request description. GitHub only interprets these keywords when the pull request targets the default branch of the repository, so for other base branches you need to close the issue yourself.
Should I open a draft pull request?
Yes, when you want to share work in progress or run CI before the change is ready. Draft pull requests do not request reviews from code owners; they are notified when you mark it ready for review. Mark it ready once CI is green and the description is complete.
How do I mark a breaking change in a pull request?
State it clearly at the top of the description and list what callers need to change. If your team uses Conventional Commits, add ! after the type, as in feat(api)!:, or a BREAKING CHANGE: footer, which release tooling reads as a major version bump.
Sources (8)
Checked against these, last on 13 October 2026.
- Small CLs, Google Engineering Practicesgoogle.github.io/eng-practices/review/developer/small-cls.html
- Writing good CL descriptions, Google Engineering Practicesgoogle.github.io/eng-practices/review/developer/cl-descriptions.html
- How to handle reviewer comments, Google Engineering Practicesgoogle.github.io/eng-practices/review/developer/handling-comments.html
- Best practices for pull requests, GitHub Docsdocs.github.com/en/pull-requests/collaborating-with-pull-requests/getting-started/best-practices-for-pull-requests
- Linking a pull request to an issue, GitHub Docsdocs.github.com/en/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue
- About code owners, GitHub Docsdocs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
- Conventional Commits 1.0.0, Conventional Commitswww.conventionalcommits.org/en/v1.0.0/
- git-commit Documentation, Gitgit-scm.com/docs/git-commit
Related on Sefism
Picked from the other libraries by shared topics.
Roadmaps
See allCheat sheets
See allBest practices
See all- Code Review Best PracticesCode review best practices for reviewers and authors: the approval standard, what to look for, review speed, writing kind and useful comments, handling disagreement and small changes.
- Git Best Practices for DevelopersGit best practices for everyday work: clear commits, clean branches and pull requests, rebase vs merge, safe force pushes, secrets, signing and recovering mistakes.
- Technical Writing Best Practices for EngineersTechnical writing best practices for developers: write for your audience, clear sentences, scannable structure, design docs, READMEs and docs, PR descriptions, async updates and blog posts.
Project structures
See all- VS Code extension project structureA TypeScript extension for Visual Studio Code, built from the official Yeoman generator with esbuild bundling. The example, TODO Lens, finds TODO comments and shows them in a tree view, with commands, settings and editor decorations. The tree grows from the generator's Hello World into commands, providers and editor-free core logic, then tests on three operating systems, publishing to the Marketplace and Open VSX, and a webview with a strict security policy. For students who use VS Code every day and want to build a tool other developers install.
- Python package and CLI project structureA command line tool published to PyPI, laid out the way the Python Packaging User Guide and uv recommend: a src layout, one pyproject.toml for metadata and every tool, a thin Typer CLI over plain, testable modules, and releases uploaded by GitHub Actions with trusted publishing. The example is mdlinks, a tool that finds broken links in Markdown files. For students who have written Python scripts and want to ship one that strangers can
pip install. - TypeScript npm library project structureA small, typed npm package (a retry helper) built the way modern libraries ship in 2026: TypeScript source in
src, bundled by tsdown intodistwith type declarations and anexportsmap, tested with Vitest, checked with publint and Are the Types Wrong, versioned with Changesets and published from CI with npm provenance. For students who want to publish their first package, and for anyone whose package works locally but breaks for users.
Career questions
See all- How do I learn Git and GitHub properly instead of just copying commands?Learn the model first: commits are snapshots, branches are pointers, and remotes are copies. Then use Git daily on your own projects, practise a team workflow with branches and pull requests, and break things on purpose, such as merge conflicts, so you learn to recover calmly.
- How do I build a developer portfolio as a beginner with nothing to show?Start with two or three small but complete projects that solve a real problem, each with a clear README, screenshots and a live link or easy run steps. Put them on a simple one-page site or a tidy GitHub profile. Depth and finish matter far more than the number of projects or a fancy design.
- What should I do in the summer after my first year of computer science?Use it to build one real project, get comfortable with Git and a second area of programming, and try one thing outside class such as a hackathon, open source or a small internship. Keep a weekly schedule of 15 to 20 hours and leave room to rest. You do not need to master everything this summer.
Stuck on something specific?
Writing only gets you so far. If you want an answer to your situation rather than the general case, book a session and we will work through it together. Sessions are free for approved Sefism members, and a few slots open each week.
- 1:1 Mentorship
- Fresh Graduate Mentorship
- Career Guidance
Brand deals, promos and partnerships: tauseeffayyaz@gmail.com