Help
cancel
Showing results for 
Search instead for 
Did you mean: 

Contributing to Repositories with GitHub Desktop

GitHub Staff

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:

 

  • We will be using the `master` branch when referring to the default branch of the repository. This can sometimes have a different name, like `development`.
  • The `upstream` repository refers to the parent repository of the fork we are creating. When we use the convention `upstream/master` we are referring to the `master` branch of the `upstream` repository.

 

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.

 

 

forkagain.png

 

 

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`.

 create_a_fork.png

 

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.

 

new_branch.png

 

 

 

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:

 

  • Did you make a large number of changes to a file but only want to commit a portion of those changes? GitHub Desktop supports partial commits, which allows you to create multiple meaningful commits.
  • Did you accidentally make changes that you no longer want to commit? GitHub Desktop lets you quickly discard specific changes to files. If you need to recover discarded changes they can be found in the Recycle Bin (Windows) or Trash (macOS).

 

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.

 

merge_again.png

 

 

 

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.

 

  • Click `Fetch origin` in GitHub Desktop to fetch any new changes from the remote repositories (even though it only says `Fetch origin` GitHub Desktop will fetch from both the `origin` and `upstream` remotes in this instance).
  • Go to the `History` tab and in the `Select Branch to Compare` box choose `upstream/master`.

 

check_upstream.png

 

  • If everything is up-to-date then you can proceed to step 7.
  • If there are new commits available to merge click `Merge into master` to merge the changes from the `upstream/master` branch into your local `master` branch. GitHub Desktop will again let you know if there are any merge conflicts that need to be resolved.

 

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.