The main way of contributing to an open-source project that is hosted on GitHub is via a pull request. A pull request says, “Here are some changes that I have made in my copy. Please incorporate them into the main version of the program.”
(Also see Version control concepts and best practices.)
git clone firstname.lastname@example.org:USERNAME/REPONAME.git
where USERNAME is your GitHub username. (In any example command, you need to replace any text in ITALIC CAPS.)
cd REPONAME git remote add upstream https://github.com/OTHERUSER/REPONAME.git git fetch upstream
When you are ready to start on a unit of work, such as fixing a bug or implementing a feature, create a branch. A branch is a parallel thread of development — you can create as many branches as you want in your repository, which is like having multiple independent repositories.
To create a branch named MYFEATURE and switch to it, run
git checkout -b MYFEATURE
(Use a descriptive, readable name for your branch, such as
You can switch to an existing branch by executing a command such as
git checkout MYBUGFIX
When you commit changes (with
git commit) or push commits to
git push), they are saved to the current branch.
Each branch should represent a logical unit of work. If you are doing two different tasks (or if while doing a task you discover a second, distinct task), then create two different branches for them. This is a bit of a hassle for you, but it makes reviewing your changes much easier, and the maintainers will be more likely to accept your changes.
Don't work on the
master branch in your fork. If you do so,
future pull requests will be cluttered by unnecessary merge commits. The
rest of this section explains why; you can skip it unless you want to learn
When a developer merges your work into the main repository, that usually creates a new commit (it contains the same code changes, but has a different identity than the one or more commits that you made in your branch). Whenever a branch isn't identical to upstream, pulling from upstream will create a new merge commit. Once a brach is different from upstream, each pull will accumulate more changes (differing commits) from upstream.
Therefore, it is better to keep your
master branch identical
to upstream, and create a new branch for each pull request. You will
delete the branch when your pull request is merged into the upstream
If you do create a pull request on
master, then after it is
merged, you are probably best off deleting your GitHub fork and all clones
of it, and then re-creating it. Only do this if all its work has been
merged upstream! There are other ways to fix the problem, but they are
Before you start to implement your changes, write tests that currently fail but will pass once you have fixed the bug or implemented the feature. Run the tests locally to confirm that they currently fail. (The project's developer documentation will tell you how to do this.) Now, commit the tests and push them. Check that Travis CI has run the project's tests on your fork and that they failed.
Now, do your work, testing locally and committing logical chunks of work as
you go. You can push these commits to GitHub by running
push whenever you like. Eventually, you will be done and ready for
a code review.
Being done requires at least the following:
Periodically pull upstream into your branch; that is, incorporate into your branch any work that other maintainers have done since you created your branch. It's easier to do this frequently than all at once. Here are two ways to do so:
git pull upstream BRANCHNAMEor
git pull https://github.com/OTHERUSER/REPONAME.git
If this command had any effect, then:
Once you are happy with your work and you believe it is ready to be incorporated into the project's main repository, you can create a pull request.
Make your code self-explanatory. You should not write pull request comments on lines of code, and you should write very little in the introductory comment to your pull request. Comments in a pull request will never be seen by a programmer reading the source code. If there is information that is needed by a programmer reading the sourece code, you should put it in a code comment. This also applies to answering questions from reviewers: it is better to clarify the code or add documentation, rather than answering a question in the pull request comment thread.
Sometimes you want feedback on your code before you are ready to merge it into a different fork. In this case, you can create a pull request between two branches of your fork.
Sometimes, you want a review of code that you have already pushed to GitHub. Or, you want a holistic code review to critique the design of an entire component of your code, rather than incremental code reviews of bits and pieces of it.
GitHub's pull request mechanism does not support this workflow well, but here are two ways to make it work.
masterinto it. You will never merge that pull request, but will merely address feedback in
masterand eventually close the pull request without merging it.
master(that is, do
git checkout master; git checkout -b review). Now, the reviewer reads and edits the
reviewbranch in their normal editor, adding TODO code comments. The author also edits the
reviewbranch, until there are no more TODO code comments in the diff. Then, merge the branch into master.
As soon as you receive feedback, you can start working on it. The reviewer should send you a message and/or assign the code review back to you, but the reviewer might forget, so don't wait for those events.
Make sure you are
working on the right branch; use
git branch to check.
Never force a push with
git push -f. Forcing a push is bad
practice, may corrupt your pull request, and will cause extra merges or
merge conflicts for people who have cloned your branch (such as the
people doing the review).
Go through each piece of feedback.
When you push commits to GitHub, the pull request will be automatically updated. If you change a line of code on which you received feedback, that feedback is no longer shown by default. That is, GitHub assumes that if a line near a review comment has been changed, then the review comment has been resolved. This means that you should try not to push changes (such as a change to indentation) that change a line without addressing all the comments related to that line.
git remote prune originin your working copy to remove from your clone branches that have been deleted from the remote repository, so that you don't accidentally use them.
Some Git documentation recommends rebasing, amending commits, or other changes to existing version control history. Don't do any of these things. They are confusing and error-prone, they can corrupt your pull request, and they are not necessary. All of your changes will be squashed and merged into a single commit when your pull request is accepted, so don't worry about what the version control history of your branch looks like. Just focus on its differences from the upstream's master, which you can see in your pull request.
You will receive email about comments to your pull requests. Don't reply by email. Instead, reply on the GitHub webpage that is referenced by the email. One reason is that if you reply by email, you may needlessly bloat your response with all the quoted text from the email you received. Another reason is that if you reply by email, GitHub may not associate your comment with the right thread in the code review.
This section is for maintainers who are reviewing and merging a pull request.
This section is currently incomplete, but contains a few tips.
When a pull request is ready to be merged, it may consist of many commits. Future maintainers will not be interested in each individual commit, only in the overall feature — this is also what you have seen while you were reviewing.
To keep the version control history clean, select “Squash and merge” when you merge a pull request. This results in a single commit that contains all the changes in the pull request.
There is no need to retain the history of the pull request. Because the change should be a single logical unit, and because it has been tested and reviewed, it should be presented to future maintainers atomically. Don't litter the git history with little commits, such as showing bug fixing within the logical change or interactions during the pull request review.
A side benefit is that every commit on the master branch passes tests.
When you squash-and-merge a GitHub pull request, the default commit message is the concatenation of the messages for all the commits in the pull request. This information is not useful to future developers. Therefore, edit the commit message. Usually the very first commit message, or the pull request's title and description, make a good commit message for the entire pull request.
Another problem with not editing the commit message is that it may leave "[ci skip]" in the commit message, so the merge commit will not be processed by continuous integration such as Travis. (CI may perform some action on every (successful) commit to master.)
Back to Advice compiled by Michael Ernst.Michael Ernst