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.
— Sindre Sorhus (@sindresorhus) March 21, 2015
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.
This article might help you to get started: Git Explained: For Beginners
Create a GitHub account
Every serious dev needs one. No, really! Go to https://github.com, create one and link it to your local Git shell.
Ok, I have something to contribute. How should I proceed?
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! .
Check the README.md & referenced guidelines
Definitely check the README.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)
- commit messages guidelines (for example: angular.js, atom.io ).
- coding rules
- …
Ok, ready to get started!
Now it’s time to pack out your Git Jedi tricks.
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:
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.
Step 3: Polish your history, squash unnecessary commits
Usually when you develop, you may have lots of commits, even intermediate ones, with commit messages that probably only you understand (if even..!).
Use 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.
Step 4: Push it to your forked repository
Now, push your branch to your repo:
$ git push --set-upstream origin my-new-feature
Step 5: Submit your PR
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.
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
$ 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.
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)
| Reference: | GitHub: be Social, Contribute, Learn from our JCG partner Juri Strumpflohner at the Juri Strumpflohner’s TechBlog blog. |
