GitHub: be Social, Contribute, Learn
How to properly contribute to a GitHub based open source project
5 min read
5 min read
OSS tip: If you want a bug fixed faster, submit a PR with a failing test rather than an issue.— Sindre Sorhus (@sindresorhus) March 21, 2015
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…
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.
This article might help you to get started: Git Explained: For Beginners
Search whether someone else already proposed it or already submitted a fix. GitHub has a simple, yet excellent issue tracking system.
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 😉 .
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
Note, many repositories contain dedicated CONTRIBUTING.md files which have detailed guidelines for contributing. Example: Angular CONTRIBUTING.md.
Now it’s time to pack out your Git Jedi tricks.
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.
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:
If you don’t wanna dive into it right now, at least create a feature branch for your change. This is highly recommended.
$ git checkout -b my-new-feature
Now it’s time to code: implement your changes.
Usually when you develop, you may have lots of commits, even intermediate ones, with commit messages that probably only you understand (if even.. 😁).
git rebase to polish your history and only include those that are relevant and help the author to more easily review your changes. Here’s how to do it: Polish your feature branch commits.
Now, push your branch to your repo:
$ git push --set-upstream origin my-new-feature
Once you pushed your branch to your repo, simply open it on GitHub. A prominently highlighted message should appear, inviting you to create a PR.
Click the “Compare & pull request” button and fill out the details.
Wohooo, you did it! Your PR is done! 😄
GitHub also has an excellent guide on how to do it.
Btw, you can simply push additional commits to your forked repo’s feature branch and they’ll automatically appear on your PR.
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
$ git remote add upstream <the repo url>
Once you have that, you can sync it by doing
$ git checkout master $ git pull upstream master
Or with a
git fetch followed by a
git merge (based on your prefs).
Here’s the GitHub Help page article that might also help.
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! 😄 😉 😂 :+1: 👏 (this might be useful)