This article is a simple guideline on how you could contribute to gitHub OSS projects using fork and upstream. This is not the only way to do it. git Extensions is used for this demo, but any git client can be used. In this example, aspnet/AspLabs from Microsoft is used as the target repository.

So you have something to contribute, cool, that’s the hard part.

Before you can make your contribution, you need to create a fork of the repository where you want to make your contribution. Open the project on github, and click the fork button in the top right corner.

Now clone your forked repository

In git Extensions, click the clone repository and select a folder somewhere on your computer.

Now you have a master branch and also a server master branch of your forked repository. The next step is to configure the remote upstream branch. This is required to synchronize with the parent repository, as you might not be the only person contributing to the repository. Click the Repository menu in git Extensions and add a new remote repository with the url from the parent repository.

Now you can pull from the upstream repository. You pull from the upstream/master branch to your local master branch. Due to this you should NEVER work on your master branch. Then you can also configure your git to rebase the local master with the upstream master if preferred.

Once you have pulled from the upstream, you can push to your remote master, ie the forked master. Just to mention it again, NEVER WORK ON YOUR LOCAL FORKED MASTER, and you will save yourself hassle.

Now you’re ready to work. Create a new branch. A good recommendation is to use the following pattern for naming:

<gitHub username>/<reason-for-the-branch-in-lowercase>

Here’s an example:

damienbod/add-urls-check

By using your gitHub username, it makes it easier for the person reviewing the pull request.

When your work is finished on the branch, you are ready to create a pull request. Go to the parent repository and click on the ‘New pull request’ button:

Choose your working branch and select the target branch on the parent repository, usually the master.

NOTE: if your branch was created from an older master commit than the actual master on the parent, you need to pull from the upstream and rebase your branch to the latest commit. This is easy as you do not work on the local master.

If you are contributing to an aspnet repository, you will need to sign an electronic agreement before you can contribute.

If you are working together with a maintainer of the repository, or your pull request is the result of an issue, you could add a comment with the github name of the person that will review and merge, so that he or she will be notified that you are ready. They will receive a notification on gitHub.

Now just wait and fix the issues as required. Once the pull request is merged, you need to pull from the upstream on your local forked repository and rebase if necessary to continue with you next pull request.

And who knows, you might even get a coin from Microsoft.

Thanks to Andrew Stanton-Nurse for his tips.

I am also grateful for tips from anyone on how to improve this guideline.

Links:

http://asp.net-hacker.rocks/2016/12/07/contributing-to-oss-projects-on-github-using-fork-and-upstreams.html

https://gitextensions.github.io/

gist from CristinaSolana