Congratulations! Reviewers deemed your Pull Request is ready to merge.
If you're at this point then you probably have a decent understanding of what Pull Requests are and how they work. If you don't, that's ok - just go back to the main Pull Requests overview post, read up on PRs, and come back.
the glorious good-to-go look of a GitHub.com reviewed PRYou now have some interesting choices to make - namely:
- "when" to merge your PR, and
- "how" to merge it.
The "when" is totally subjective and depends on how modern of a workflow you're rockin'. Up-to-date methodologies tend to deploy code more often (and we learned in our above overview post that merging a PR is mostly how you "deploy" code these days) so merging asap makes sense.
Legacy methodologies rely more on human effort and time slots, often waiting to merge PRs until some manual step happens or a staging queue frees up. Not great.
ai generated image via "an illustration of a software continuous deployment system being outdated, artistic and impactful"The "how" is a bit more nuanced, so we'll go into specific details in a bit. You have a few choices to make here called a "merge method". If your repo owner aligned this properly already then there won't really be more than one option, making it click-the-button simple.
GitHub.com Repository PR settingsIf they haven't made it simple, you'll need to pick one of the methods below.
Three options are available (at least on GitHub) for getting the code merged into the destination branch (also called the destination branch).
This is the default method, and isn't one I'd suggest. It adds all the commits in your feature branch and turns them into a "merge commit" that goes into the destination branch.
GitHub PR merge method: merge commitThe reason I generally don't do this is due to how the histories of the branches are affected. The changes on the feature branch live in their own branch of history, and are "merged" in a separate commit beyond the actual code change commits.
git history after merging a PR via merge commitI find this a bit excessive and clutters up the git history when looking at it. If you're a solo dev then the methods here don't matter as much, but I find the next option a bit cleaner.
This is my go-to method, for good reason.
GitHub PR merge method: squash and mergeIt combines all the commits - similar to the first method - but "squishes" them into a single commit housing all the changes across the entire feature branch at once. When merging this way, it's as if you did a normal commit into the destination branch all along outside the PR process.
git history after merging a PR via squash and mergeThis keeps the history very clean - there's 1 commit into the production branch for each feature branch that was ever merged. This not only makes reading changes in git history easier, but also makes reverting changes much simpler.
If you don't like what happened after merging a PR, you can revert the entire single commit of those changes in one go.
This last method is as though you were coding on production the entire time (at least the history will look that way).
GitHub PR merge method: rebase and mergeIf you're a solo dev then this is probably fine, but I'd argue the Squash and merge method is cleaner for when something goes wrong, and you need to revert an entire body of work.
There's plenty of valid opposing opinions on this, so do what's best for you.
git history after merging a PR via rebase and mergeIf something goes wrong and you need to revert something with the Rebase and merge method, you'll have to guess which commit (and if you're following my previous advice, there'll be a lot of commits, all day every day) broke it and hunt around. When prod is broken, you don't have time for that.
Just go with Squash and merge.
This is what the git history looks like now, after having done one of each pull
request merge method (and deleted the local branches so it's only the remote
main branch remaining):
git history after merging 3 PRs in the three different methodsIf you're fortunate enough to have an Enterprise GitHub account then you'll have access to a handy thing called a "merge queue".
GitHub.com merge queue featureInstead of directly waiting for all your required PR checks to pass & reviewer approval before you can merge your PR, you can add it to GitHub's queue. Once all the checks pass / approvals are in, it will take the next item in the queue, update it with the latest changes on the destination branch (in case it's changed recently), and merge it.
This is handy for bigger development groups where lots of people filing and merging lots of PRs keep trying to cut in front of each other. Whoever gets their PR merged first triggers a mandatory update on everyone else who was waiting in line, re-starting the race to be next.
Merge queue takes care of that.
ps. this is assuming you have the "Dismiss stale pull request approvals when new commits are pushed" setting enabled, which I do recommend.
If for some reason you need to bail on a PR or change directions, that's fine - just "close" the PR.
Closing a PR - try to add comments saying "why"It won't merge, and the changes you created and the comments & checks listed will be preserved for archival purposes. If you want to pick it back up, you can technically re-open it, but I'd recommend just starting a new branch "from" that branch (merge in main to be on the latest code set) and start fresh.
Keeping a bunch of dormant open PRs your repo becomes a bit of a mess to sort through, so try to close out your PRs by merging or canceling. It's a little like leaving trash lying around instead of throwing it away; makes it harder to navigate in a clean and efficient way.
Once you've merged in your Pull Request, it's time to watch it deploy!
Practicing good ownership mandates you care about your changes landing where they should go - successfully. To do that you can either manually watch the various workflow screens in a bunch of tabs, or just watch it in a Portal.
Read more about that in the "Aftermath" section of our Pull Request overview post.
