Contributing to Repositories with GitHub Desktop

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.

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

 

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

  1. 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).
  1. 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

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

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

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

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

4 Likes