Ultimate Guide to Pull Requests

If I write this correctly it'll be the last guide you'll ever need to read about pull requests.

Aimed at software engineers of all levels my hope is you'll better understand:

• why Pull Requests (PRs) matter
• how to create/review them like a boss
• getting the most value in the least amount of time
• ideal PR workflows

...and then share this post with your friends/team to do/learn the same.

My general viewpoint on software is that it's a means to an end. That end is typically making a company money.

ai generated image via "a blog post about writing software to make money,cartoon illustration"

Unless you're building something solo, for fun, or out of generosity - then you're doing it to generate someone revenue (usually in exchange for a paycheck).

Don't get me wrong - I love writing software! Though if we're being honest, it's to make a living.

This guide/series will cover Pull Requests in their entirety - specifically from that angle. I call it "Profit Engineering" - writing code to make a profit.

Put another way: writing code that makes more money than it cost to create & maintain - not code that's perfect, "cool", or impressive to interviewers.

This requires a different way of thinking and can be uncomfortable at first, but time and time again this mindset has proven invaluable to many a business and can undoubtedly increase your perceived value as a contributor.

ai generated image via "an illustration representing changing one's thinking, happier"

This won't be your typical guide. I'll share a lot of opinions and advice that might directly go against the suggestions of others. Or the industry norms for that matter.

I can almost guarantee you'll find yourself in a debate or debacle with another technically-minded individual about how strange, odd, and/or wrong these opinions might seem.

ai generated image via "an illustration about revolting to improve writing software"

Technical specialists & purists are greatly appreciated, impressive, and provide an important piece in the tech ecosystem... but that's not who we're here to impress.

In Profit Engineering, we'll measure our contributions by business value - not tech savviness. Let's begin!

A "pull request" is a term used to describe an official request for code in one branch of a version control system (git most of the time these days) to be merged into another branch.

Typically, this looks like human developers working on a feature in their own isolated copy of a codebase and when ready to make their changes "official" for everyone else to use, ask permission to merge it back in.

They create a Pull Request - abbreviated as a PR - and ask people to review it. If those reviewers are ok with the changes, they "approve" the PR, and it's changes are merged back into the codebase where it began.

Creating a new branch from that codebase has these changes in it, and the cycle repeats. PRs are just the conduit for asking permission - and getting it - to coordinate code merging into places.

Without a PR you'd merge your code back in without review and without safety checks, becoming quite risky, error-prone, and a security risk.

But where did the concept of PRs even come from? They technically aren't part of version control systems themselves, but as a layer on top of them.

First, a brief history lesson. Linus Torvalds technically invented the concept of a git-request-pull back in 2005 (and git itself earlier), but it was the GitHub hosting platform that popularized it into a feature called Pull Requests in 2008.

Linus Torvalds

Other vendors have similar concepts but call them different things - like "merge requests" - but the original concept of "pulling someone else's code into your own" kept the name going.

This kick-started the PR methodology of collaboration across developers, teams and organizations still going strong today. Filing PRs to move one bit of code to another has its pros n' cons, but ultimately nothing better has taken their place.

The rest of this guide will assume you're using GitHub. They're arguably the oldest/best/most popular git repository hosting service in existence (some alternatives being GitLab, Bitbucket, etc.).

I'll use the GitHub-specific terminology and features, but they can be applied to other vendors just fine.

I know what you're thinking - "ok, thanks for the history lesson, but why should I care?". Touché.

Pull Requests have become such a pivotal part of the modern software development ecosystem that I wrote a whole separate article explaining why.

ai generated image via "an illustration about Pull Requests being the most important thing in the world"

Helping get your code into production, facilitating collaboration across multiple developers & teams, providing opportunities for mentorship... and other more "interesting" concepts.

See the real reason why Pull Requests exist.

Now to be completely fair, not every developer needs to use pull requests.

They have a TON of benefits and are almost always worth using, but there are some cases where their benefits juuuust barely don't outweigh the costs.

The most obvious example would be a company that doesn't do anything with code or technology. Yes, those do still exist... I think? If there's no code, there's no PRs.

Solo devs also should ask themselves "is it worth it?".

Coordinating code changes between multiple people makes PRs a given, but when going into the tech alone, it's worth pausing to validate.

Let's assume they're worth doing (because they are) - so what's next?

This is likely why you're here - either you're curious or someone linked you to this section. We'll cover all you need to know about creating/filing/using Pull Requests for Profit Engineering.

ai generated image via "an illustration about a huge amount of things all going into one place, cartoony"

There are a LOT of options, vendors, tools, and methodologies to consider - but we've found most of them to be technical noise. We must keep in mind the whole point of why we do PRs in the first place!

PRs are a way to get code into production to make a company more revenue. Beyond all the myriad of benefits they provide along the way, that's the ultimate goal.

If a vendor makes that too expensive, a tool ends up being too complex & confusing, or a methodology is too outdated to move quickly - then ditch it!

ai generated image via "an illustration of throwing something away quickly, cartoon style"

To help you weed through this noise and save you time, we've written up a more detailed guide on how to create PRs with making money in mind.

See how to make money with Pull Requests.

Half the value of a Pull Request is in the automations, robots, checks, deployments, and other bells & whistles that save a bunch of time and money doing normal software developmenty things.

The other half lives in the "human" realm - teaching, safeguarding, approving, validating, and all the other risk-management type of things a company might want to enact.

ai generated image via "a cartoon illustration about guarding from risk"

PRs provide an excellent opportunity to teach and guide younger developers, and to get snapshots of different areas of work your colleagues are tinkering in. These and many other perks are the bread n' butter of PRs, but come at a cost - namely, time.

There's a lot of subjectivity in finding this balance of robots & humans, so I went into a bit of detail outlining what I believe is the most universally applicable PR workflow for most orgs to generate a profit.

Learn the best pull request workflow ever created.

So far we've covered "creating" PRs - but let's discuss the flip side of that: reviewing them.

Pushing code into a branch, filing a PR, notifying whoever about it, and moving on isn't quite enough. This is where a lot of opinions and advice will differ - and for good reason.

Each company / team might have different reasons and expected outcomes for PRs; some might purely want them for training junior engineers, others might use them as a way to get code into a long-lived staging environment.

The more modern orgs might use PRs as a conduit for automating sequences in their software development lifecycle, which is the camp we fall "mostly" into here.

ai generated image via "a cartoon illustration representing modern automation"

I firmly believe reviewing Pull Requests should be easy, fast, and provide a high degree of value as a ratio of the cost of human involvement within them. Aka PRs should make more money than they cost to manage.

This is a careful balance and important to get right - so I put it in its own article (again).

See my 1 minute pull request review hack.

Once your PR gets approved by however many reviewers you've specified (we suggest just 1 in most cases), and passes all the automation checks you've added (you did add them... right?), then it's time to merge!

... but how? There's several ways to merge in a PR - some better than others.

Squishing, squashing, merging, rebasing, oh my!

ai generated image via "a cartoon illustration of squishing code commits into a single commit for a pull request"

To help you weed through the pros n' cons of each, I've written up a more detailed guide on how to go about it.

Merge PRs better than your boss ever could

Wew! You've made a PR, the checks have passed, humans said "good enough", and you merged it! Now what?

Remember that Pull Requests are vehicles for putting code from one branch into another. That means by merging the PR, the destination branch (most of the time main / production) just got updated. When branches get updated, you should have workflows setup to deploy those code changes where they need to go.

Now that the main branch just got your new code, it's on you to make sure those changes get where they're supposed to go - and that they do what they're supposed to do.

I realize you can merge code in a PR into other branches besides production, but for all intents and purposes lets assume you're merging to production. It's the normal thing to do these days (boo long-lived staging environments).

Your workflows should kick off and all the checks you utilized in your PR are likely also running on those changes in your production branch (main). However, since your PR is closed, there's no real decent place to "watch" those checks and their pass/fail states.

Using GitHub's UI directly, you can navigate to your repository's "Actions" tab, find the workflow(s) relevant to your type of code changes, and try to watch them as they progress.

Or, just add a "workflow" widget to a WTP Portal to keep an eye on more easily. It'll show you little green/red circles with context (if you hover over them) as to what's going on, and you can click one to instantly go to that step / fail in the relevant workflow.

selecting the Pull Request widget inside What the Portal

No more hunting around for things once your PR merges - just check your Portal on occasion to make sure things landed right.

seeing all PRs in one place inside What the Portal

If you did your automated testing & feature flags correctly (which the human reviewer should have verified) then it's unlikely for issues to pop up... even though on occasion they do. Context differences, after all.

Not only should you watch to see if changes to the destination branch fail any automated checks, but you should also make sure your code changes get deployed successfully to wherever it is they're going.

Even after all the checks pass and things look peachy in the production branch, it can still fail "getting" to production. For this you'll have to look at wherever you do your deployments.

OR - you guessed it - just add a "deployments" widget into your Portal.

selecting the Deployments widget inside What the Portal

It'll give you that glanceable red/green status update in near-realtime with how your deployments are going. Hunting around for deployments leaves the GitHub context (most of the time) even further than hunting for destination branch changes.

seeing all Deployments in one place inside What the Portal

You're still responsible for ensuring the code gets deployed correctly, but you can at least make it easier on yourself to verify that happens. Save yourself the headache of all those tabs... just use a Portal.

Wew ok so your PR merged, your code updated main successfully, and those new changes to main were deployed correctly. Nicely done! But you're still responsible for those code changes "working" in that environment.

They're your changes after all, and we're practicing ownership here - so be diligent.

I'm not suggesting you have to log in, look at the destination environment, enable the feature flag(s) hiding your changes, and verify them visually. That's a lot of time and effort for something not even being released yet.

What I am proposing is you make sure nothing existing newly breaks - which is most easily done by watching for new error logs. Services like Sentry do a fairly decent job at flagging new-found errors & logs that weren't there previous, so if you suddenly start seeing an influx of things after your code deployed - then you know something's up.

To see that information you can open up more tabs like Sentry's UI itself, hunt around for logs relevant to your timeframe and/or project and/or environment, and flip back n' forth to see if anything pops up... but let's be real, that's a lot of distracting work.

So how can we 1) practice ownership by proactively monitoring our changes, while 2) keep working on the next Pull Request? Use a Portal!

Add an "events" widget to your Portal. Boom, done.

selecting the Events widget inside What the Portal

Now alongside your PR widget, workflows widget, and deployments widget you'll also see errors & logs. Now you're starting to get the full picture and see the far-reaching context your code changes really.

seeing all Events in one place inside What the Portal

Owning your code changes makes you stand out as a software engineer and is core to Profit Engineering. Own a piece of work, get it done fast, deliver it promptly, and care enough to see it through to real usage.

The effort required to practice this isn't for the faint of heart - there's a lot to keep track of all while pushing forward simultaneously. That's exactly why we created What the Portal - to help the best engineers stay the best while making things a tad bit easier for them.

Here are some frequently asked questions about PRs with links to more details.

Dismissing stale pull request approvals is a useful setting in git providers that removes old approvals once new code is pushed to the branch. This forces reviewers to look at the code again & grant a new approval for a merge to be allowed.

more details