How to Create Good Pull Requests
Put quite simply: the easier it is to read & understand your PR, the easier it is to get it approved & merged!
Each of the following sections address different topics that you can follow or avoid when creating a new issue.
Refer to the GitHub help docs for guidance on creating forks, PRs, syncing forks and the basics of working with PRs in GitHub: Collaborating with issues and pull requests.
- Create a good title
- Fill out all sections (and remove guidance)
- Referencing related issues
- Verify there are no conflicts
- Atomic PR's & minimize number of commits
- Monitor your PR for followup requests
Follow the same guidance provided in How to create a good issue: Create a good title.
Follow the same guidance provided in How to create a good issue: Fill out all sections (and remove guidance).
When submitting a PR, it's important to be clear on three main points:
- what the PR is (for example: new content / fixed content / etc)
- what it addresses (existing issue... see the section on Referencing related issues for more information)
- what's in the PR
The quicker someone can understand what the PR is, the quicker we can get it merged in. Otherwise, someone has to pick through each commit in the PR to understand what it includes.
- fill out all requested information in each section
- delete the block quote "helper" text
- ignore the sections and post your issue at will
- leave the "helper" text - it serves no use in the issue other than helping you create a good issue
If the PR addresses existing issue(s), please reference them in the appropriate section. If you use GitHub's autolinking feature, it will add a link to the issue(s) making it easier to track progress on the issue.
To create a reference, simply prefix it with # (for example, issue 0000 would be #0000).
For more information, see GitHub Help: Autolinked references and URLs.
When referencing an issue, if you use special keywords, the related issues are automatically closed when the PR is merged.
To reference an issue, use the keywords fixes or closes before the issue reference. Make sure you use the keywords before each issue as each one needs the keyword to get closed.
// this works
fixes #0000, fixes #9999
fixes #0000, closes #9999
closes #0000, closes #9999
// this won't work
fixes #0000, #9999
closes #0000, #9999
After submitting a PR, GitHub will add a section at the end of all comments indicating the state/health of the submission.
If this section says This branch has no conflicts with the base branch, you're in good shape.
However, if it says This branch as conflicts that must be resolved, you need to fix this before we can consider merging it. What this means is that you are making changes that will overwrite existing changes. Refer to the GitHub help for more information on Resolving a merge conflict.
If there's a conflict, we'll ask you to fix it. Refer to the section Monitor your PR for followup requests.
- ensure there are no conflicts with the base branch
- submit and ignore a PR that has conflicts
When submitting a PR, please don't include a large number of commits or group a lot of changes in a single PR. Just like creating code commits, each commit should do a single thing. If you are fixing 5 different issues that are not related, that should likely be submitted as 5 different PRs.
If 3 of those issues are part of the same fix, then maybe it makes sense to include 3 commits in a single PR that fixes 3 issues at once.
- keep PR's atomic
- include a large number of commits in a single PR
- unless they are all related, don't fix multiple issues in a single PR
After submitting a PR, please monitor the PR until it's resolved (merged or closed).
All PR's are reviewed and we may request changes before we can merge it. If you fail to respond to our feedback or change requests, we'll have no choice but to close the PR due to no response.
- monitor and address feedback or change requests on your PR
- ignore change requests on your PR
-
Getting Started