Github 102: Submit a Pull Request¶
This tutorial outlines the steps to submit a pull request. You should have a basic familiarity with the concepts discussed in Github 101: Set Up a Fork.
Only submit a pull request after you have finished programming and testing your proposed additions to the codebase.
Before you submit your changes, add yourself to the contributors list. Most projects have a list of contributors in their GitHub README or elsewhere in the repo.
Commit All Changes and Rebase¶
Commit your changes. Verify that you have committed everything by running git status on your working branch.
Ensure there is nothing to commit and the working directory is clean. If uncommitted changes exist, commit the changes if needed. If these changes are not needed, discard the changes; you may need to recompile and rerun the tests.
Pull in changes made by others.¶
Pull in changes made by others since you forked your repo and replay your commits on top.
git pull --rebase upstream master
The operation “replays” your work on top of the commits that have happened since you began. For more information, see http://git-scm.com/book/en/Git-Branching-Rebasing.
Resolve any conflicts that may occur during rebase.¶
git status will give you detailed instructions on the necessary steps to resolve any issues. Once resolved, git add the resolved files and use git rebase --continue until you’re done rebasing.
Recompile and test.¶
Rebuild the code to ensure that you have merged successfully. If you have added any new asserts, rebuilding the code can catch new assert code conflicts since each assert must have a globally unique error number.
Rerun the tests as well to ensure other changes has not broken your changes, or vice versa.
If you have multiple commits, squash your commits into a single commit.
Get hash for interactive rebase.¶
In preparation for git interactive rebase, view the commit log to find the hash of the commit immediately preceding your first commit in this branch.
Perform interactive rebase.¶
Using the hash from the previous step, perform the interactive rebase.
git rebase --interactive <hash>
Alternatively, you can specify HEAD~<number of commits you made> instead of the hash, as in git rebase --i HEAD~3
Squash all but your first commit.¶
An editor will open a git-rebase-todo file with a list of your commits. Skipping the first entry, update the remaining entries, changing pick to s for squash.
pick 0300bf2 first commit message s 6516cc2 second commit message s 8cfca09 third commit message
Save and quit out of the editor.
Update comment for the commit.¶
An editor will open with the list of commit messages involved in the squash.
Update the first commit message to reflect accurately the changes you made. The message should include the ticket number. For example, PYTHON-555: Support $out aggregation pipeline operator.
Delete everything else that comes afterwards in the file that is not a comment.
Ensure that the commit message is clear and complete. Avoid ambiguous messages, such as SERVER-100: MongoDB allows foobar input. It is unclear whether the message is describing a bug that was erroneously allowing foobar input or whether the message is describing the fix that now allows foobar input.
A better message might be: SERVER-100: Mongo should allow foobar input or SERVER-100: Stop allowing foobar input to Mongo.
Submit a Pull Request¶
Verify state of branch.¶
Verify that you are in the appropriate branch and that you have squashed your work into a single commit.
Publish your branch.¶
Publish your working branch to your forked repository.
git push -u origin <BRANCH-NAME>
For more information on pushing to your fork, see http://stackoverflow.com/questions/2765421/how-to-push-a-new-local-branch-to-remote-repo-and-track-it-too.
Go to your repository.¶
Go to the your forked repository on the GitHub site. Near the top of the page, click the pull request button.
If you are submitting to the SERVER project (aka, mongo/mongodb), you must sign and return the contributor agreement before your pull request can be added to the project.
The Life-Cycle of a Pull Request¶
When you submit a pull request, here is what happens:
- The engineering team will review your pull request to make sure you have included a JIRA ticket in your request and signed the contributor agreement if applicable.
- You may receive a response from one of our engineers with additional questions about your contributions. If we cannot accept your pull request, you will receive an explanation of why we cannot accept your pull request.
- If your pull request matches a ticket and aligns with the project’s roadmap, the appropriate team will triage and review your request.
- If approved, we will sign off and merge your request into a development branch and resolve the associated JIRA issue with an expected fixVersion.
Remember to show off your accomplishment by requesting a contributor T-shirt once your first patch has landed.
Most importantly, thank you for your contributions.