A Polite Guide to Pull Requests – InApps 2022

Fun fact: Did you know you can easily see the very first pull request of any GitHub user? And I do mean any user.

That fun little page popped up as I am gearing up for the Dec. 1 kickoff of 24 Pull Requests. Yes, it’s that most wonderful time of the year again! Doing this got me to thinking about my first PR. And, honestly, the fact that there aren’t many subsequent PRs in my personal GitHistory. Last year, when I first heard about the 24PR initiative, it was like a week before Xmas. Not only was I late to the party, but as a n00b I wasn’t even sure how to go about identifying an open source project to contribute to. Much less go about opening a pull request that wasn’t, like, totally wrong and, subsequently, totally embarrassing.

So now it’s somehow magically a year later, and time to get real about actually doing this thing. Thankfully, I’m much less worried about embarrassing myself this time around, I’ve done it so much these past 12 months that I sort of don’t even notice anymore, so I’m just going to dive on in. That said, it occurred to me to maybe do a bit of pre-24PR prep so that maybe I waste project maintainer’s time just a little bit less with my newbie attempts at being helpful. Here are some of the things more experienced GitNinjas tell me to keep in mind before throwing a PR at perfect stranger — basically, Pull Request Etiquette.

Ask First

Sometimes the first step to opening a pull request is not to open a pull request.

Yes, it’s pretty obvious, but if you’re an excited first-timer sometimes you’re in a bit of a hurry and might not think to ask. So, if you’re approaching some cute project that has caught your roving eye, it’s best to start by opening an issue. Creating an issue is not just for reporting a bug you’ve spotted in someone’s code — it’s also a means to approach project maintainers with suggestions, requests, whatever you got.

For the love of Linus, test and debug. The best way to make a PR is to submit clean, organized, readable code free of mistakes and glitches.

And it’s good for all involved here. What if the creators have a good reason they don’t want to add that super cool idea for a project feature you are really excited to tell them about? Or, what if they already had the same super cool idea and it is already in progress? Before you start writing code for someone else’s project, it’s a good idea to first open an issue and, you know, ask about it.

Branch Out

K, so you found a bug or a typo or have an idea for an additional feature; you opened an issue, communicated with the author, and they said: “Yes, please.” W00t! It’s code o’clock! Well, almost.

First, create a branch for that shiny new code. Branches are best for working on any project feature or fix, and PRs are no exception. It goes without saying to name the branch

This is always a good idea when working on a specific feature or fix for any project, and PRs are no exception. Of course, you’re going to name your branch something concise, readable and directly corresponding to the change you are suggesting.

Style Right

Ok, another thing that is good to do before you go and write your beautiful code: check out the target project’s particular style. Every project has one, and it’s bad form to go changing things just because you think they way they’ve been doing it is wrong or dumb or violates some pet peeve of yours.

For example: check out the variable names. If the author uses camel case, so should you. Ditto the commit messages: strive to match the language and style the authors chose for their commits. Look for other important structural aspects, too — like If the project has a test suite, you should be writing tests for any code you’re contributing. Remember, we are supposed to be helping, not making extra work for the maintainers.

Work Your Magic

(This is the part where you actually write code, wheee!).

Now clean it up.

Take a thorough look at what you’ve made. For the love of Linus, test and debug. The best way to make a PR is to submit clean, organized, readable code free of mistakes and glitches.

However, mistakes can be missed — and authors can certainly, and legitimately, ask for changes before finally merging your PR. So rebasing is very important at this phase. Even if you catch your mistake and fix it in a subsequent commit, the project maintainers are likely to read the commits chronologically, see the mistake/bug/problem first, and only later find out you already fixed it — like, after they spent 15 minutes diagnosing and writing their request.

Plus, authors ultimately want one solid, clean commit — not half a dozen reworkings and fixings leading up to the final flawless code contribution. So: rebase to condense and clean up any previous commits, and merge branches based on the latest commit. (Because you’re keeping your branch current with master, right?)

And Submit!

Trusting you’ve already got that part down.

Fa la la la, only (25 – Date.now() ) days left in this year’s 24PR party!