Contents
Pull rejection sucks!
You have just coded, implemented, and submitted a pull request. A short while later the request is declined by an upstream maintainer and you feel crushed. We have all been there. Today I'm going to show you a better way. This article will teach you how to create pull requests that get approved.
Start small
You need to earn trust with the maintainers. Your first commit should be a small change which they cannot reject. Try to write a missing test or re-factor duplicate code. Correct a comment's accuracy or rename a variable to better reflect its purpose. Your first pull request should not alter how the program works.
Don't add leading or trailing white space
Additional whitespace will alter the diff output. This causes version control systems to flag lines as changed which is irritating and sometimes misleading.
Less is more
Minimize the number of changes to accomplish your goal. People are busy and at times lazy. Reduce the work the maintainers must do to perform a merge. Lowering the amount of lines to review should increase the chance of approval.
Only commit working code
Do not break the program, only commit working code. If the project has tests make sure they work before you commit.
Follow the leader
Try to mimic the maintainers. Follow the coding style and project layout even if it seems wrong. This is not your playground... yet. Before you commit, review the VCS logs to learn how verbose or terse your commit messages should be. When in Rome do as the romans do. This silly game of follow the leader reduces friction of an outsider committing to the project.
Comments, docs, and tests oh my!
Your first pull request should clarify or add to the existing documentation. Fix the README, adjust a comment, or write a test. These tasks might appear small but they serve to prove that you possess comprehension of the source code. They also do not alter the program's functionality.
Having a few of these pull requests under-your-belt will earn you trust which will eventuality translate to more responsibility in the future. You will also differentiate yourself from the rest because most people do not enjoy working on documentation.
Blog about the change
Write about the change, give reasons and examples. Include a link to your blog post in the pull request.
Pull requests are like paragraphs
If you were writing an essay, you would split up your ideas into separate paragraphs. A pull request has many qualities similar to a paragraph. Each commit should be related to the pull request's main objective. Commits of a pull request should stay focused and on topic.
A pull request is to a program as a paragraph is to an essay.A commit is to a pull request as a sentence is to a paragraph.
In an essay, if you have more then one topic you should have more then one paragraph. Likewise when coding, only one idea or change per pull request.
Separating your ideas into different pull requests will grant the maintainers greater flexibility when they begin to integrate. They will have the ability to pick-and-choose which requests to merge and everybody wins!
