GitHub Desktop is a great tool for different collaborative development models. In this article we will be walking through using GitHub Desktop with the 'fork and pull' model. This model can be used within an organization you belong to that contains a private repository you do not have push access to but need to commit changes to, or within an open source project that you would like to contribute to. You can read this guide for more information about contributing to open source projects.
A note about the conventions used in this article:
1. Create a fork of the repository you would like to contribute to.
The first step you will need to take is to create a fork of the repository that you would like to contribute to. You can follow GitHub's guide on how to fork a repository for more information about that process.
2. Clone your newly created fork to GitHub Desktop.
You can either clone your newly created fork directly from GitHub to GitHub Desktop using the green `Clone or download` button on the repository's page, or directly within GitHub Desktop by going to the file menu and selecting `File` > `Clone Repository`.
3. Create a new `topic` branch in GitHub Desktop.
Git has a branching model that makes it easy to quickly create lightweight topic branches. Topic branches are created to implement a specific change, like a feature or bugfix. Create a new branch in GitHub Desktop from the branch dropdown with the appropriate title for the change that you are going to make. Creating topic branches like this helps ensure that the `master` branch only has code in it that you will eventually want to merge back into the `upstream/master` branch.
4. Review and commit your changes.
This is your time to contribute. Start making your changes in your favorite text editor or integrated development environment (IDE). GitHub Desktop supports a number of text editors, which means you can conveniently open your repository directly in your editor of choice without even needing to switch applications. When you have made some progress, commit those changes using GitHub Desktop.
Some notes about committing:
5. Merge your `topic` branch back into the `master` branch.
Now that you have finished creating commits in your `topic` branch you are ready to merge them back into your `master` branch. Switch back to your `master` branch, select `Branch` > `Compare to Branch` from the file menu, and choose your `topic` branch from the branch list. GitHub Desktop will notify you of any merge conflicts, which you can then resolve in your text editor before merging.
6. Check for any new commits that have been made in the `upstream/master` branch.
You are almost ready to submit a pull request to the `upstream/master` branch. First, you will want to make sure that there are no new changes that have been pushed to `upstream/master` that you need to merge into the `master` branch of your fork.
Your local `master` branch is now up-to-date with `upstream/master`, and you are ready to submit your pull request.
7. Submit your pull request.
You can begin the the process of creating a pull request within GitHub Desktop by going to the menu and selecting `Branch` > `Create Pull Request`. This will launch your default browser and and take you directly to the page on GitHub where you can open a pull request.
8. Make any additional changes requested for your pull request.
The next step in the process is for a maintainer of the upstream repository to review your pull request. They may suggest some changes for you to make, and you can use GitHub Desktop to commit those changes and push them up to the `master` branch of your fork. Your pull request will automatically be updated to reflect the new commits that have been pushed.
You may also be asked to resolve merge conflicts if new changes that conflict with your proposed changes have been introduced since your pull request was opened. Simple merge conflicts that are caused by competing line changes can be resolved directly on GitHub, but more complex merge conflicts will need to be resolved locally on your machine.
9. Your pull request gets merged!
Congratulations! Your pull request has been approved and merged. Enjoy that lovely green square on your contributions graph and go ahead and find the next bug to squash.
You must be a registered user to add a comment. If you've already registered, sign in. Otherwise, register and sign in.