As software teams strive to deliver value faster, pull requests are a focal point for accelerating development cycles.
However, managing pull requests effectively is easier said than done.
Between keeping branches up-to-date, reviewing code, fixing merge conflicts, and testing across environments, it’s no wonder pull requests often lead to bottlenecks.
In this guide, we’ll walk through best practices for creating, reviewing, and merging pull requests to help your team collaborate better and ship code faster.
We’ll follow an example story of a fictional team at DevApp Inc. to see how implementing pull request guidelines step-by-step can have a meaningful impact on velocity.
Setting the stage—DevApp Inc.'s pull request woes
Let’s consider a hypothetical company—DevApp Inc.
DevApp is a startup building a platform for selling widgets online. Their engineering team follows agile principles and practices continuous delivery with an Ops culture.
However, as the codebase and team grew over time, their pull request process became inefficient:
Pull requests sat open for days or weeks before being reviewed.
Reviews were superficial and missed critical flaws.
Merge conflicts happened frequently, slowing things down.
There was little testing before merging to master.
As a result, new features and bug fixes took way too long to ship. The constant patching of regressions also ate into precious development time between releases. DevApp’s velocity declined sharply.
The CTO decided enough was enough. They took seven specific steps to help improve the efficiency of their internal workflows.
Let’s look at what steps they took and understand how you, too, can improve your team velocity through better pull request practices.
Step 1: Write useful pull request descriptions
DevApp Inc struggled with vague pull request titles like "Fix issue #12345." This made it difficult for reviewers to prioritize or understand changes.
To fix this, DevApp Inc. decided to standardize the Conventional Commits specification for all pull requests and commits. They now require all commit messages to follow the structured format:
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]
For example:
fix(auth): resolve encoding issue causing sign in failures
Fix UTF-8 encoding of auth token to address sign in issues on iOS.
Users were unable to sign in on iOS causing decreased engagement.
Updated LoginViewController to encode token before sending.
Reviewed-by: Jane
Refs:
The commit type (fix, feat, docs, etc.) communicates the intent. This helps teammates understand what was fixed or added from the commit message alone.
DevApp Inc. also required PR descriptions to follow a template with sections as below:
- Fixed encoding issue in LoginViewController causing auth token to be invalid
- Updated to use UTF-8 encoding before sending token
- Users were unable to sign in on iOS causing decreased engagement
- Encoding fixes the issue based on analysis
- Low risk of regression
- Manually tested sign in flow on iOS 13/14
[ ] Code builds clean
[ ] Added tests
[ ] CI passes
[ ] Peer reviewed
This information helps reviewers understand the context of the code changes at a glance.
Keep it simple. You are communicating with a person, not writing code all over again. And writing a long, complex description is just creating more work for the person on the other side. Short, concise and descriptive PRs get reviewer juices flowing, and ultimately move the process more smoothly along. — Gonzalo Bañuelos, Cloud Engineer and Entrepeneur
The descriptive summaries helped reviewers better organize and prioritize pull requests. PRs got picked up faster for review as reviewers now knew what was within their domain.
However, it’s a challenge to ask developers to write large PR descriptions. At Graphite, we faced similar problems during development. We are currently experimenting with Graphite AI to automatically understand what files changed and how those changes impact the project, enabling the auto-generation of descriptions for developers to modify and enrich with nuances.
Step 2: Keep pull requests small
Next, work towards a “1 PR = 1 feature/fix” rule.
No more cramming multiple unrelated changes into one massive PR! Developers should split up changes across multiple small, focused PRs.
For example, instead of:
Big PR: Apple Pay Integration + Guest checkout fix + Product reviews
They would now open stacks of small, atomic PRs:
PR 1: Apple Pay integration
PR 2: Allow guest checkout with invalid postal code
PR 3: Add review summary to product page
Small PRs make code reviews drastically easier. Reviewers can thoroughly inspect the changes without getting overwhelmed. Approvals then start happening much faster as a result.
Additionally, since each PR contained isolated changes, there were fewer instances of code conflicts or things breaking unexpectedly in staging.
However, stacking with GitHub is unnecessarily complex, which can deter developers from implementing that workflow. You need a tool that’s built to improve PR velocity.
That’s where a tool like a Graphite comes in.
While GitHub works well as a version control system, it can be challenging to manage when teams scale and need to ship code faster. This is where tools like Graphite come in handy.
Graphite seamlessly integrates with GitHub to help developers create smaller, focused pull requests more easily:
Stacking workflow: Easily split up tasks across branches with automatic stacking. Group-related branches to ship collectively.
PR inbox: Like an email inbox for PRs. The advanced custom filters allow developers to organize pull requests in customizable sections based on author, labels, review status, and commits. You can use this to keep context when handling multiple PRs.
CLI: Create, checkout, and view PRs without context switching from the command line.
VS Code extension: Git GUI tightly coupled with stacking workflow allowing you to stack directly from your IDE.
With Graphite, DevApp Inc.'s developers could break down tasks into independent units of work and ship incrementally. The integrated dev environment also enables context switching between branches and PRs with minimal overhead.
Graphite's smart features enhance GitHub workflows to facilitate the creation of smaller PRs. Developers stayed unblocked with less context switching, helping DevApp Inc. ship code changes faster.
Step 3: Make code reviews more collaborative
The previous changes accelerated the individual phases of the PR process. But DevApp Inc. also wanted to improve the code review experience itself.
Instead of back and forth between the author and reviewer, code reviews were made more collaborative. This was done by encouraging devs to review each other’s code frequently.
The fresh perspectives help reveal gaps, prevent blind spots, and produce better solutions—before they even reach the code review stage.
It’s easy to fall into a place of being overly harsh with feedback, but a code review is a great place to show some empathy and build rapport. Talk about what was good, what could be better, and don’t be a logic bully as Adam Grant would put it. — Robert Wood, Operating Partner, Sidekick Security
Reviewers also need a more inquisitive, less judgmental tone when asking questions or seeking clarifications. The motive of a comment must go from critiquing code to suggesting solutions. For example:
To further improve collaboration, code review tools like Graphite offer centralized PR inbox that gives focused visibility into all pending tasks.
Step 4: Break down reviews into checklists
Studies show that checklist-driven code reviews increase defect detection rates by over 66.7% compared to non-checklist-based methods.
DevApp Inc.’s team analyzed the types of defects that frequently slipped through reviews. These ranged from security flaws and performance issues to not following coding conventions.
They decided to create review checklists around five key areas:
Security: Validate inputs, prevent injections, enforce HTTPS, etc.
Correctness: Handles edge cases properly, no obvious logic bugs.
Architecture: Aligns with existing patterns, maintainable code.
Performance: No n+1 queries, inefficient loops, repetitive IO ops.
Style: Follows naming conventions and code styles.
Reviewers now methodically inspect PRs against each checklist item before approving. This kept reviews consistent regardless of who was reviewing and ensured nothing major slipped through the cracks.
If you need inspiration, here’s a code review checklist a reviewer shared on GitHub.
The upfront effort in building these checklists can pay off greatly over the long run as your reviews become more intentional and focused, speeding up the time it takes to review PRs and giving authors more actionable feedback. Also, treat the checklist as a living document that should be updated and adjusted to suit your team’s growing needs.
Step 5: Adopt a dedicated code review tool
While GitHub provides built-in code review features, they remain fairly basic and restrictive for optimizing workflows at scale. GitHub's interface also makes it tedious and challenging to filter requests for effective prioritization.
A fast-moving team like the hypothetical DevApp Inc. would start to bottleneck as more developers are added and the number of PRs starts growing exponentially.
You need something to help you properly organize code review tasks without overwhelming the users. That's why high-performance teams often adopt dedicated code review tools for simplifying pull request management.
For example, Graphite aggregates all pull requests across repositories into unified, customizable views—filterable by the developer, reviewer, status, age, priority attributes, and more, for effective prioritization.
At a glance, developers could easily spot workload distribution imbalances—helping them keep the tasks moving while they proactively balance reviews teamwide. Graphite offers visibility not just into volume, but key PR metrics like first response times and completion rates too.
The built-in routing algorithms recommended reviewers based on expertise fit, availability, and past pull request cycle times. @mention notifications integrated seamlessly with Slack and the powerful VS Code extension enabled quick task switching.
Step 6: Define SLAs for pull request turnaround
After implementing the above changes, things started moving faster for the DevApp team. But without actual metrics, tracking pull request SLAs, velocity gains depended too much on individual effort levels.
DevApp Inc. decided to track cycle time performance at each stage and define time-bound SLAs:
Time to first review: Initial feedback given in ≤24 hrs.
Publish to merge time: PR is merged or closed in ≤5 days.
These were integrated with custom analytics using Graphite. Their automated monitoring gave real-time visibility into throughput and bottlenecks.
When SLA breaches happened, the team investigated why, for example, a PR waiting days to be picked up? Who dropped the ball? How can we improve here?
Just having the structure for accountability drove more discipline. Moreover, the data gave them confidence they were shipping value reliably and faster.
Step 7: Automate testing pre-merge
Like many development teams scaling quickly, DevApp Inc. struggled with maintaining code quality. With engineers shipping features rapidly, bugs still slipped into production—despite diligent QA and code reviews.
Manual testing had become a bottleneck to DevApp Inc.'s rapid development velocity. To address this common scaling challenge, they started including pre-merge automated testing.
Set up CI/CD pipelines to auto-execute tests on every pull request.
Included end-to-end integration and performance validation instead of simple unit tests.
Security scans automatically checked and verified dependencies.
Now, when engineers open PRs, these pipelines run rigorous quality checks on the changes. If any test failed, reviewers were immediately notified to request adjustments from developers which greatly improved dev velocity.
Streamline adoption of PR best practices with Graphite
None of these practices are revolutionary individually.
But by improving each phase—creating, reviewing, merging PRs—you can compound small gains into an exponentially faster development cycle.
The key insight is recognizing the synergies between process steps—you must work on the bottlenecks while strengthening safeguards simultaneously. This balanced approach allows teams to ship faster without quality compromises.
So, start by analyzing your current PR workflow end-to-end. Look for high-leverage areas to drive efficiency through tools, automation, and better collaboration.
If team adoption is the challenge, try Graphite. It is purpose-built to help improve workflows by subtly enforcing PR best practices:
Graphite integrates seamlessly with GitHub so you can start seeing benefits in minutes without disrupting your team's existing workflow.
The smart productivity features help implement many of the guidelines covered here, like creating smaller PRs, tracking SLAs, automating testing, and more—all with minimal configuration.
Graphite was built by scaling engineering teams to help them collaborate better. The UI and workflows are designed specifically to streamline PR processes end-to-end.
"Graphite makes it much faster for me to develop because I’m spending less time wrangling git" — Rodda John, Engineer at Ramp
Take the first steps towards significant dev productivity gains. Sign up for a free Graphite account and experience the productivity boost for your team. The effort is well worth the results!