The Git and SourceTree beginner's guide to contributing to open-source projects in GitHub - Part 1 - Essential concepts
Contributing code to open-source projects on GitHub requires a working knowledge of Git. Let’s be honest, Git can feel intimidating and the command line downright scary.
Don’t let that stop you
Luckily Git is more approachable than it seems and there are ways around the command line.
Using Concrete5's public GitHub repository let’s see how we can contribute code to it with the help of SourceTree a free Git GUI for Windows and Mac.
This guide assumes you already have a GitHub account. If not go ahead and create one, I’ll wait.
How about GitHub Desktop?
GitHub offers its own free desktop Git GUI: GitHub Desktop. Why not use that?
I looked at it when it first came out and, as a beginner, I wasn’t impressed. Although it’s a trimmed-down GUI I found it confusing and couldn’t figure out some of the things I needed.
I started working with SourceTree and found it easier and more complete.
I am sure GitHub Desktop has come a long way since my first try so by all mean give it a go and see for yourself.
You can also check this list of other Git GUIs for Windows. Yes, I’m a PC guy.
The essential concepts you’ll need to understand
Repository: This is where your files are, where your code is preserved. You can have a local repository (on your computer) and a remote repository (on GitHub or elsewhere) and you will usually work locally and later push the code remotely.
Fork: To fork somebody else’s repository means to make a copy of it under your own Git environment, your GitHub account for instance. Under the same GitHub account, only one fork of each repository is allowed. Typically you fork a repository so you can work on it.
Clone: When you have a remote repository (on GitHub or elsewhere) and you want to make a local copy (on your computer) you clone it.
Branch: To branch one of your own repository means to create a new copy of your code under the same repository. One repository can have as many branches as needed. Branches are used to work on specific features or fixes without touching the main branch. The main branch is usually labeled “Master”.
Checkout: To checkout a branch means to make that branch the currently active branch, the one you are working on. All the other branches still exist but they are not used by you. You can only checkout one branch at a time while other developers might be working on other branches. You can go from one branch to the other by just checking out the one you want.
Commit: To commit your changes to your branch means to add to the branch you are currently working on whatever modifications you brought to your code. You will add a description or message to your commit so you can keep track of what you did. When working on open source projects, those commit messages are very important as they allow others to know what you’ve been doing.
Push: After you committed some code to your branch, you might want to send it to your remote repository, on your GitHub account. You Push it from your local repo to your remote one so both are in sync. Well, at least the branch you are pushing will be in sync with its remote copy. Other branches might differ. Pushing is only possible for repositories you own or if you were granted that permission.
Pull request: For repositories which you don’t own and that didn’t grant you the right to push to then directly, you have to ask them to pull the code themselves (instead of you pushing it) from your repository to their own. So you send a Pull Request basically saying: here’s some code I wrote you might be interested in. Please review and if you approve, grab it.
Merge: If you were able to push your code or if your pull request was accepted, your code will be added to the branch. It will be merged with it.
Steps to contribute to an open-source repository
Your first 2 steps are always going to be the same: fork and branch. And yes said like that it does sound dirty, but bear with me.
- First, you fork the repository to your own GitHub account so you can work on it.
- Then you create a branch because it is just good practice. You don’t want to start working directly on the main branch if you’re going to have to try different things and you might want to create other branches or the original main branch later on.
Now that you have your fork and your branch what you do depends on how much code you want to contribute.
Sometimes you have something really small to contribute. You noticed a typo or you fixed just one or a few lines of code, probably modifying only 1 file. In that case, you can work directly in GitHub, it’s just easier.
Some other times you have more important modifications to offer, over several files and lines of code. In that case, you’ll be better served to work locally first then pushing to your remote forked repository. This is where SourceTree will come in handy and will keep you free from the command line.
In that situation, you will still start with the same 2 steps above with one tiny extra step before following the next steps. It goes like this
- Fork the open-source repo you want to work on so it’s in your own GitHub account
- Using SourceTree, clone your fork so you have a local copy on your computer (the tiny extra step)
- Create a branch locally and give it a meaningful name
- Work on your local branch, writing code
- Commit your code to your local branch with a meaningful message every time you feel you finished a unit of work and are going to start on something else. The idea here is that you don’t want to have just one big commit at the end with one huge message. You want your work to be committed in mostly standalone and small-ish chunks.
- When you’re done writing code, push your branch to your remote repository
- Finally, send the original repository a pull request so they can review and accept your code and merge it with their own
What’s next
Now that we understand the basic Git concepts and workflow, let’s get our feet wet and get some actual work done. In part 2 of this guide, we’ll go through the first few steps described above using the GitHub’s interface directly in the browser.
