Juri Strumpflohner

Juri is a full stack developer and tech lead with a special passion for the web and frontend development. He creates online videos for Egghead.io, writes articles on his blog and for tech magazines, occasionally speaks at conferences and holds training workshops.

How to properly contribute to a GitHub based open source project

GitHub revolutionised the open source world by building - IMHO - the first true social coding site. It has never been that easy to contribute to a project, whether it is to simply discuss some new features, to file a bug or in the best case to submit a bug fix or new feature patch: a pull request (PR). Still, I found lots of devs don’t know how to properly create a PR, yet. With this article I hope to lower that entry barrier.

OSS tip: If you want a bug fixed faster, submit a PR with a failing test rather than an issue.

First of all…learn git

Git is the most widely used version control system, especially for Open Source projects. While you could use SVN on GitHub as well, most projects don’t. Simply because Git is much more suitable for the use case of distributed working, where multiple people from around the world clone, fork and submit new changes to your repository.

That said, you have to know the basics of Git and get used to how it works. Hence, you should know about…

fetch, pull and push

checkout

HEAD, master

status

add and commit

reverting and undoing changes

branching and merging

rebase

remotes

I highly recommend you to take the time and study these, get used to them, play with some local demo repository where you try them out (without breaking anything). Trust me, this will save you a lot of trouble and pain.

Ok, I have something to contribute. How should I proceed?

If it is a bug, create a failing test, try to reproduce it locally. Good repos already have a good test harness in place. Then submit your fix as a PR (including a test that verifies it’s absence).

If it is a new feature proposal, I personally recommend to get in touch with the author(s). Create an issue and propose your enhancement and new feature. In that way you gain additional insights from the author or core contributors and especially you avoid to go in a wrong direction. Submitting new code that doesn’t get merged because the author thought about it differently, hurts. Believe me .

Check the README.md, CONTRIBUTING.MD & referenced guidelines

Definitely check the README.md and/or CONTRIBUTING.md, which is automatically rendered in a nice readable way at the root of the GitHub repo. Many repos include instructions for building the repository and especially guidelines for contributing, building etc!

Thus, verify whether there are

guidelines requiring automated tests for your new changes (that’s always a good idea, even if they’re not explicitly required)

Ok, ready to get started!

Step 1: Fork the repo

The first step is to fork the repo you’d like to contribute to. GitHub does that for you, simply search for the fork-button:

This will automatically create a copy of the repository under your own GitHub user profile.

Step 2: Clone your forked repo

Now that you have a copy within your own GitHub user profile, you have full read/write access and you’re ready to apply your change/feature implementation to the codebase. Clone your fork and start coding.

At this point we have to speak about “git flow”. This term comprises a couple of strategies and good practices when working with git. Here are a couple of helpful articles:

Link/Sync with the original repo

If your contribution was a one-time bugfix, you can also delete the repo once it is merged. Instead, if you intend to contribute further changes, you might want to setup a link to the original repository s.t. you can update your own repo’s master from now and then.

This is done by adding another git remote that points to the original GitHub repository

Conclusion

Contributing is vital for keeping the Open Source ecosystem alive, and you learn a lot while doing so! At the same time, though, respect the author’s guidelines, be polite and, use Emojis, they’re there with a good reason! (this might be useful)