These days, when you update code, you often do it via a pull request. You write code, create a pull request, and hope that your changes are accepted.
Pull requests and code reviews are scary. Posting your code for someone to critique is nerve-wracking. Doing it in public is terrifying. Here are some tips to make it all a bit less scary.
Communicate
A pull request should start with communication. The person reviewing the code should confirm that the update you want to make will be welcomed. You should confirm what you will be doing and even how you will do it. A pull request shouldn’t be a pop quiz. It should be a take home exam, where you can ask the teacher how to answer the questions before you go home. And then you can ask follow up questions as you are working on the test. Communication ensures that you are coding a fix that everybody wants.
Stay Focused
Now that you know what you want to do, deliver what you promised, but not much more or less. Don’t add extra “drive-by” fixes. If you spot a bug somewhere else in the code, don’t fix it in this Pull Request. Create an issue so that it can be fixed later on, and stay focused on the purpose of your pull request. Don’t try to do more than one thing in this pull request. Pull requests targetting one item are easier to read and review. Getting a single pull request merged is hard. Don’t make it harder by adding in some extra things that stir up more questions and discussions.
Test
Demonstrate your pull request works with tests. Add new tests to show that your update works. Or note which failing tests are restored. Code reviewers don’t have to rely on your word or their mental debugging skills to be sure everything works. The tests in the pull request prove that the code works and document the normal and edge cases that you’ve considered. If the repository isn’t easily testable, at least describe what tests you manually did to prove things work. Including some screen shots or standard output may be the best you can do, but it’s better than nothing.
Fit in
Make your code look like the rest of the existing code. Whatever style conventions exist, mimic them. No matter how much you dislike the conventions used in the code base, just go with the flow. If you add code that doesn’t fit in, it’s harder to read. It’s also somewhat insulting to the original authors.
Cheat
If you’re nervous about submitting a pull request, look at other pull requests that have already been closed or are being reviewed in the repository. You can see what sort of reasons other pull requests were rejected or accepted. You can see what sort of questions people ask. This will help you avoid common mistakes.
What else?
If you’ve done all of the above, you’re in a good position to get your pull request accepted. Do your best to write good code with good commit messages. Then, go ahead and submit with confidence.
Top comments (0)