This tutorial assumes you are working on a repository TheRepo whose main instance is hosted by an organization TheOrg with a main branch TheBranch. (TheRepo, TheOrg, and TheBranch are placeholder values that you should fill in based on the repo you're using.)
1. Fork TheRepo on GitHub to create your fork TheFork (only needs to be done once):
In the top-right corner of the page, click Fork.
See example at GitHub: Fork A Repo
(Don't actually follow the exact steps on this page; use it as an example and apply the steps to the repo you're using.)
2. Clone a local version of the code from TheFork (and follow any other necessary installation instructions for the repo):
git clone git@github.com:yourusername/TheRepo -b TheBranch
3. Always start from the latest version of TheBranch from TheRepo:
git remote add upstream git@github.com:TheOrg/TheRepo
git fetch upstream TheBranch
4. Make a new topic branch to track your new features:
git checkout -b YourBranch upstream/TheBranch
5. Edit the code, compile, and test.
6. Stage your changes once they work, create atomic commits, and push back to TheFork:
git add your_changed_file.cc
git commit -m "explanation of what was changed and why"
git push origin YourBranch
(If you want to commit all changed files at once, use git commit -a -m "...".)
7. Before submitting a pull request (see step 8 below), check to make sure that the upstream repository has not been updated with new changes while you were developing your new features. If the upstream repository was updated and your changes no longer merge automatically, you need to rebase:
git fetch upstream
git rebase upstream/TheBranch
Rebasing will undo your commits, add in the new commits from upstream, and then redo
your commits on top of the new upstream commits. There may be merge conflicts if
you and someone else both made changes to the same file. In that case, Git will
insert merge conflict markers
into the affected file to point out the location and contents of the conflict.
Resolve the conflict manually by editing the file, then use git add <file> to save the changes you made,
and continue the rebase:
git rebase --continue
Once the rebase finishes, push to your remote fork:
git push -f origin YourBranch
Note: because git rebase rewrites history, if you already pushed YourBranch to the remote before rebasing (always a good idea!), the -f option will be necessary when you push the rebased branch.
8. Send a pull request to TheRepo (branch TheBranch) on GitHub:
GitHub: Using pull requests
In the pull request comments, you can provide a more detailed description of your changes.
9. If you need to make additional changes to the pull request before it is acceptable to merge into the main repository, repeat steps 5 and 6. The existing open pull request will automatically be updated with your additional commits.
10. Once the pull request is merged, start from the latest TheBranch from TheRepo again:
git fetch upstream TheBranch
then repeat step 4.
