Search This Blog

March 12, 2014

Steps in contributing to an open-source project in Github

Often times we find it compelling to contribute to someone else's project, either because you added a new feature to it or fixed an existing bug. This way you feel proud that you're giving back to the community project that helped you from re-inventing the wheel.

Git/Github has simplified and made intuitive the entire process of code contributions to other's repositories.

However, it can some times go awry if you do not get the basic workflow of working in Git right or because you're over-confident of your contributions. For the latter case, see my pull request  that was not accepted in spite of it following the community convention in user experience/design. It's a good lesson for me that re-in forced the lesson that the world is super opinionated (and that includes me as well) and that there is nothing right or wrong.

In this blog post we'll look at recommended steps in how we can contribute to other's open-sourced repository to which you don't have access and want to send in a pull request.

Step 1: Fork the target repository, say, Spoon-Knife to your account in Github (karthiks in my case).
Click "Fork" button in the Spoon-Knife repository page in Github

Step 2: Clone your forked repository to your local laptop.
$ git clone https://github.com/username/Spoon-Knife.git

Step 3: Configure Remote

This step is often overlooked. A sure sign of getting the workflow wrong.

When you clone a repository, it has a default remote called origin that points to your fork on GitHub. This is good enough if you do not intend to contribute code changes back to the original repository that you forked.

However, you are a good citizen that wants to give back to the author in the form of code contributions. For this you need to keep track of the original repository for fetching and merging the latest changes. So go ahead and add a remote named upstream pointing to the original repository:
$ cd Spoon-Knife
# Changes the active directory in the prompt to the newly cloned "Spoon-Knife" directory
$ git remote add upstream https://github.com/octocat/Spoon-Knife.git
# Assigns the original repository to a remote called "upstream"
$ git fetch upstream
Fetches any new changes from the original repository
$ git merge upstream/master
# Merges any changes fetched into your working files
Step 4: Create a feature (or bug-fix) branch and commit your changes to it. This is important step. Do not by-pass this step, if you want to pat yourself.
$ git checkout -b my-feature1-branch
# Creates a new branch "my-feature1-branch" and switches to that branch

Step 5: Push your local branch to your remote repository.
$ git push -u origin my-feature1-branch
# Pushes your local branch "my-feature1-branch" to your remote repository and makes your local branch track its corresponding remote because of the "-u" option

Step 6: Send the original author a pull request.
+ Got to your project page in Github
+ Switch branch to my-feature1-branch
+ Initiate Pull Request with the click of a "Pull Request" button


Inspiration and Reference:

My inspiration to write this blog post has come out of a mistake I did sometime back in the way I overlooked some of the steps mentioned above and sooner felt the pain of my oversight. Lesson learnt the hard way. And I hope this post comes to the rescue of good citizens. As I always say, "Failure is absolutely okay, so long as we have something to learn and not repeat the same mistake for the same reason".

Some portions of this blog content is taken, modified and/or reproduced from the Fork a Repo guide of Githubs' as it fits and connects well to this context of blog title. Thank you Github!