If you’re contributing to a project, your pull request is your chance to make a strong case for why your code should be pulled into the main branch. Make sure to put your best foot forward.
Know the audience for your Git pull request
Before you write a single word, understanding your audience is helpful so that you can focus your words on what is most useful. A pull request may serve many audiences. Keeping all of your audiences in mind is important, but your primary focus is on the folks who will review and make a decision on whether your pull request will be merged. You want to make their lives easier as they tend to be very busy.Even though the project maintainers are your primary audience, you should never forget that many others will read the pull request. For an open source project, that audience may be the entire world. So, keep your language respectful, friendly, and inclusive.
It’s pretty common to have someone write a pull request in a fit of anger and later regret the words they use. So if you happen to be rage coding, take a moment to cool down and gather your thoughts before creating the pull request.
Make the purpose of your GitHub pull request clear
Make sure to be concise and informative. For example, the summary should make the purpose of the pull request clear. The summary is the only part shown on the page that lists pull requests. It needs to be scannable.Here are some examples of good pull request summaries:
- Adds the About page to the website
- Minimize boilerplate setup code for JavaScript libraries
- Extract and isolate error handling from GitStore internals
- Teams are forever
- Typo
- Small changes
The description should provide a bit more explanation about the purpose of the pull request. Don’t write a book, but do make it clear what the pull request attempts to accomplish.
Keep your GitHub pull request focused
Much like a commit, a pull request should not contain a bunch of unrelated changes. A pull request may consist of multiple commits, but they should all be related to the task at hand.You can often tell that a pull request is doing too much when writing a concise description of what the pull request accomplishes is difficult.
Even if the pull request is focused on a single major change, keep the pull request to a manageable size. Reviewing a very large pull request is difficult.
If the pull request addresses a very large task, break down the task into smaller steps and submit pull requests for each step.
Explain the why behind your GitHub pull request
The previous suggestion focuses on what the pull request does. You also need to explain why you’re taking on this work. The pull request description is an opportunity to provide links to other documents that provide more context. You can’t assume everyone will be familiar with the history.If you have a lot of context to share, you can provide a brief summary followed by more details within a <details> tag. For example, if you add a pull request comment with the following text:
The reason we're embarking on this work is due to compliance reasons.
<details>
## More Details
I don't want to bore everyone with all the nitty gritty details, but for those who are interested, keep on reading…
</details>
GitHub displays the details section collapsed by default, as shown.
Details section collapsed.Click the details label to expand the details section, as shown here.
Details section expanded.How to add an image to your GitHub pull request
GitHub supports adding images to a pull request description by dragging and dropping an image. When you drag and then drop the image on the text field, GitHub uploads the image and replaces it with the markdown for rendering an image. The following figure shows an upload in progress after an image is dragged into a pull request comment field.
Uploading an image to a pull request.This comment is very meta as it’s a screenshot of the same repository it’s a comment on.
If an image is worth a thousand words, an animated gif is worth even more. If you can create an animated gif that demonstrates the behavior change introduced by the pull request, adding that gif to the pull request is usually very appreciated by those who review it.
Include a call to action in your GitHub pull request
You need to be very clear about what feedback you want from others on the pull request. For example, if the pull request is a work in progress, make that clear from the start so that people don’t waste time reviewing a pull request that isn’t ready for review.To make that clear, follow the conventions of the repository. You can find out the conventions by orienting yourself with the repository.
Following the conventions is important so that others know what is expected of them with respect to your pull request.