I’ll never forget how nervous I was when I submitted my first pull request.
If you are unfamiliar with a pull request, it is a suggested edit for a fix in somebody else’s code in GitHub. Even though I was submitting tweaks to a friend’s GitHub repository and not a stranger’s, the fact remained that he does this kind of thing for a living and I don’t. Even though I’d scoured my code for errors, I feared that my submission neglected a key part of GitHub etiquette.
See also: GitHub For Beginners: Don’t Get Scared, Get Started
My pull request was accepted without a hitch, but first time worries are common. Web developer Rachel Nabors described her first attempt at a pull request thus:
Before I submitted my first ever pull request, I was super nervous. What if I submitted it wrong? What if there was some hidden etiquette I didn’t know about? What if I was about to breach protocol in such a way that would get me shunned from coder society for the rest of my life?
Fortunately, there are some established protocols for submitting a pull request that makes it through. Here’s everything a beginning GitHub user needs to know about pull requests.
Why Submit A Pull Request
What is a pull request? This is GitHub’s official definition:
Pull requests let you tell others about changes you’ve pushed to a GitHub repository. Once a pull request is sent, interested parties can review the set of changes, discuss potential modifications, and even push follow-up commits if necessary.
Put simply, a pull request is nothing more than the official way of telling another GitHub user, “Hey, I think you missed a spot.” When you see errors in another person’s repository, or have suggestions for how they could improve, you can submit your edits in a pull request.
See also: GitHub For Beginners: Commit, Push And Go
According to Matthew McCullough, a teacher at GitHub, submitting a pull request is the best educational experience possible for beginners on GitHub.
“It’s a huge opportunity to learn from some of the best people in the industry,” he said in a video. “You’re essentially getting mentoring for free in benefit of trade for your time and thought and investment in fixing and improving and tuning up pieces of software used worldwide.”
https://www.youtube.com/watch?v=81uKcXZoQ2A
You might be thinking, “If you’re still a beginner, should you really be submitting pull requests? Other GitHub users probably know better than you what they’re doing.” However, the whole point of GitHub is that everyone has something to contribute—that’s why it’s open source.
On the chance your pull request is accepted, you can feel good knowing you contributed to a piece of software you care about. On the other hand, if it’s denied, polite developers will write back to explain why and at least you’ll get a lesson out of the experience. It’s win-win.
Etiquette Tips For Making A Pull Request
Let’s say you’ve found an error in somebody’s code and you know exactly how to fix it. Here’s how you can submit your first pull request with confidence:
Be Clear And Specific
Technically, GitHub allows you to submit a pull request with no comment at all. But there’s a comment box for a reason. Carefully explain what the problem is and how your change fixes it. It’s also helpful to explain how the developer can recreate the problem you’re seeing. You can also include screenshots to show the tests and improvements you’ve done.
Keep Changes Small
You might see more than one bug that you’d like to fix. Be sure that if you do, submit them as two separate pull requests. A lengthy pull request is unlikely to be dealt with quickly. It could be difficult for the original developer to try and follow your steps.
Stick To Existing Conventions
Is the original developer putting spaces between functions, or putting CSS curly brackets each on their own line? Has she provided a style guide for future pull requests to follow? If so, you’ll save the creator a lot of trouble by sticking to the code style they’ve already established.
Never Copy-And-Paste Code
The point of pull requests is to fix bugs, not to add new ones. And, as I’ve learned the hard way, copying and pasting code does nothing but add bugs. Computers can be very finicky about reading the spaces in code, and copy-paste adds new spaces you can’t even see.
Read The Documentation
There’s also a GitHub Guide on contributing to open source like a pro, including some of their best practices for submitting pull requests. At the very least, you could read GitHub’s suggestions for how to have positive interactions on GitHub.
Etiquette Tips For Receiving A Pull Request
You may also find yourself on the other end of the interaction. If you have a public repository on GitHub (and all repositories are public if you have a free account), that means anyone can stumble upon your code and suggest changes.
Here’s how you can accept or deny pull requests graciously:
Don’t Fix Their Mistakes Yourself
If you get a pull request with only a slight answer, it may be tempting to just fix it and push the change. But it’s much more polite to send the request back and explain why you did so. The author might have a reason for writing it the way they did, a Quora discussion suggests.
Don’t Be Rude
This should be obvious. If somebody submits a pull request, that means they’re trying to help your project. But not everyone remembers this golden rule, and it can cause a lot of trouble. Case in point: when a node.js core contributor rejected a community member’s pull request for changing programmer pronouns from “he” to “they,” his curt response started a firestorm.
Using GitHub’s walkthrough, anybody can go through the motions of submitting a pull request that’s technically correct. But by sticking to generally accepted modes of etiquette, you can handle pull requests with the assurance that you’ve gone above and beyond.
