GitHub: be Social, Contribute, Learn

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, 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)
• commit messages guidelines (for example: angular.js, atom.io ).
• coding rules
• …

Note, many repositories contain dedicated CONTRIBUTING.md files which have detailed guidelines for contributing. Example: Angular CONTRIBUTING.md.

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:

• Understanding the GitHub flow
• Implementing the “Git flow”.

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! 😄 😉 😂 :+1: 👏 (this might be useful)