A little while ago, Damien Bowden wrote a pretty cool post about how to contribute to an open source software project hosted on GitHub, like AspLabs. He uses Git Extensions in his great and pretty detailed post. Also, a nice fact about this post is that he uses an AspLabs project as the demo project. Since we both worked on that project during the hackathon at the MVP Summit 2016, together with Glen Condron and Andrew Stanton-Nurse from the ASP.NET Team, I thought I'd write on it too!
At that Hackathon, we worked on the HealthChecks for ASP.NET Core. The HealthChecks can be used to check the health state of dependent subsystems in a micro service environment, or in any other environment where you need to know the health of depending systems. A dependent system could be a SQL Server, an Azure Storage service, the Hard drive, a Web-/REST-Service, or anything else you need to run your application. Using the HealthChecks you are able to do something if a service is not available or unhealthy.
Because Damien Bowden also worked on that project, my idea was to do the same post. So I asked him to "fork" the original post, but use the Git CLI in the console instead of Git Extensions. Because this is a fork, some original words are used in this post.
Why using the console? Because I've been a console junkie for a few years and from my perspective, no Git UI is as good as the simple and clean Git CLI. Anyway, feel free to use the tool that fits your needs. Maybe someone will write the same post using SourceTree or using the Visual Studio Git integration.
As a result, this post is also a simple guideline on how you could contribute to OSS projects hosted on GitHub using fork and upstream. This is even not the only way to do it. In this demo, I'm going to use the console and the basic git commands. Just as Damien did, I'll also use the aspnet/AspLabs project from Microsoft as the target Repository.
True words by Damien: "So you have something to contribute, cool, that’s the hard part."
Setup Your Fork
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. Click the "Clone and download" button and copy the clone URL to the clipboard.
Open a console and
cd to the location where you want to place your projects. It is
c:\git\ in my case. Write
git clone followed by the URL to the repository and press enter.
Now you have a local master branch and also a server master branch (remote) of your forked repository. The next step is to configure the remote upstream branch to the original repository. This is required to synchronize with the parent repository, as you might not be the only person contributing to the repository. This is done by adding another
remote to that git repository. On GitHub copy the clone URL to the original repository aspnet/AspLabs. Go back to the console and type
git remote add upstream followed by the URL of the original repository:
To check if anything is done right, type
git remote -v to see all existing remotes. It should look like this:
Now you can pull from the upstream repository. You pull the latest changes 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.
Start Working on the Code
Once you have pulled from the upstream, you can push to your remote master, i.e. the forked master. Just to mention it again, NEVER WORK ON YOUR LOCAL FORKED MASTER, and you will save yourself a lot of hassle.
Now you’re ready to work. Create a new branch. A good recommendation is to use the following pattern for naming:
Here’s an example:
By using your GitHub username, it makes it easier for the person reviewing the pull request.
To create that branch in the console, use the
git checkout -b command followed by the branch name. This creates the branch and checks it out immediately:
Creating Pull Requests
When your work is finished on the branch, you need to push your branch to your remote repository by calling
git push . Now you are ready to create a pull request. Go to your repository on GitHub, select your branch, and click on the "Compare & pull request" button:
Check if the working branch and the target branch are fine. The target branch is usually the master of the upstream repo.
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 if you do not work on the local master. Or, to update your local master with the latest changes from the upstream, push it to your remote and merge your local master into your feature branch.
If you are contributing to any Microsoft repositories, you will need to sign an electronic contribution license agreement before you can contribute. This is pretty easy and can bevdone in a few minutes.
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 as soon as you save the pull request.
Add a meaningful description. Tell the reviewer what they need to know about your changes. and save the pull request.
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 your next pull request.
And who knows, you might even get a coin from Microsoft.
The Console I Use
I often get asked what type of console I use. I have four consoles installed on my machine, in addition to the cmd.exe and PowerShell. I also installed the bash for Windows. But my favorite console is the Cmder, which is a pretty nice ConEmu implementation. I like this console because it is easy to use, easy to customize, and it has a nice color theme too.
Thanks to Andrew Stanton-Nurse for his tips. Thanks to Glen Condron for the reviews. Thanks, Damien Bowden for the original blog post!
I'd also be happy for tips from anyone on how to improve this guideline.