Your first open source contribution: a step-by-step technical guide
Here’s what it takes to be an open source contributor: a GitHub account, some git commands, curiosity, patience, and kindness. No expert level skills required. Thanks for your interest in helping out!
Special thanks to my open source pals Sivakumar Kailasam, Ricardo Mendes, and Braden Lawrence for feedback and review!
0. Make a GitHub account
Most open source projects are hosted on GitHub, which is a website for sharing and saving code. Anyone can make a GitHub account for free. Paid accounts are only necessary if you want some of your code to be private.
1. Choose a project and issue to work on
A set of files for a project is called a Repository, and Issues are where people ask for help fixing things. Here’s an example of a repository I help with for EmberJS. If you haven’t picked out a project to work on, here’s a site that might help you. Contributing to open source isn’t just about hardcore coding — there’s plenty of work to be done on public websites for the project (like CSS and HTML) or documentation that will help out other developers. For your first contribution, pick something small. If you want to help out with EmberJS, shoot me a message!
When you’re new to a project, it’s a good idea to comment on an Issue that you want to help with and ask some questions before doing any major coding work. To see the Issues, click on the tab for it. Many open source projects use tags like “Good for new contributors” or “help wanted” to indicate which Issues might be best to jump in on. Don’t be surprised if it takes days for someone to reply. Most open source maintainers do a little work here and there in their free time, and no one pays them for it (unless they are very, very lucky). “Maintainers” is sometimes a formal title but often it means the people who are most actively contributing or reviewing changes.
GitHub also created some guides of their own to encourage people to get started. You can check them out here if you want more in-depth reading on this topic.
2. Fork the repository (aka make a copy)
To fork a repository, look for the “Fork” button in the top right corner of a project’s GitHub page. A fork is your own personal copy of the project that you control. You can make changes and play around without affecting anyone else’s work. Here, I’m helping with an EmberJS project called Super Rentals.
Now you have your own personal copy of the project. This is where you’ll do your work. You can always find the fork by clicking on your user icon, then “Your Profile” and the Repositories tab. You can learn more about forking repositories in this GitHub Guide.
3. Clone the fork (aka download the copy)
For this next step, you’ll need to have git installed. Git is a program that helps you save the changes you’ll be making on your computer and then share them online. I recommend this git tutorial if you’re just getting started and the GitHub Guides. This interactive visualization is particularly cool. To be clear, git is a program you run on your computer. GitHub is an online website where it’s easy to store and share code.
When you click on the green “clone or download” button, you’ll see a few options. If you’re a beginner, you may want to do “clone with HTTPS.” You may need to click on “Use HTTPS” to reveal the option. You’ll see a link, which you should copy. If you use HTTPS, you’ll have to enter your username and password each time you want to save your code online. Or, you can use SSH, which is compatible with 2-factor authentication and generally better practice, but just some more work to set up. Or, you can skip all of this and use GitHub Desktop. You have options!
In the command line, navigate to the folder where you want to save the repository. On a Linux/Mac, ls will list the contents of the folder you’re in. cd foldername will open up a folder you saw in the list. cd .. will take you up one level. mkdir foldername will create a new folder. Whatever you do, don’t save your project in Google Drive, Dropbox, etc.
Once you are inside the right folder, type git clone that-https-url-you-copied. Hit enter, and your project will start downloading. cd into the folder you just opened.
4. Make a git branch
If you type git status you will see the branch name that you’re on, called master. In most projects, master is a special place where the most stable, reviewed, up-to-date code is. So, you’ll need to make your own branch:
git branch a-descriptive-name
Then switch to that branch:
git checkout name-for-your-branch
But what exactly is a branch? As a developer is working, they may want to be able to switch back and forth between the stable master code and the changes they’ve made. Branches let you do that. A branch is kind of like a fork on your computer. When you have your own branch, it’s a place where you can make changes without affecting master.
5. Install dependencies
Almost every open source project uses other open source projects within their codebase — tools for running servers, parsing times and dates, animating, etc. These are referred to as dependencies. For example, if you are helping with a JavaScript project, you’ll probably need npm. If you’re working on an Ember app, you need npm and the ember-cli. A good open source project will have detailed instructions on how to install the dependencies in its README.md and CONTRIBUTING.md files.
6. Make some commits (aka do the work)
Alright, how can I explain this without it being like How to Draw an Owl? Hopefully you have already commented on an Issue and done some Q&A about the problem you’re trying to solve or feature you’re building, and you’ve read through the README and CONTRIBUTING instructions for the repository.
When you have some code that you want to keep, you should save it in git by creating a commit. Here’s how:
git status will show you the files you changed.
git add path-to-your-file will allow you to pre-select the files you want to save. Add the files one at a time.
git status again to make sure you added the files you want to keep your work from
git commit -m "some message here #123" will group your changes together into a commit. The message should be short, describe the work that you did, and include the issue number that you are working on.
git push origin name-for-your-branch to save your work online. You’ll be prompted for your git username and password. Up until you type this command, your work has only been saved on your computer. After this, if you look at your Fork on GitHub, you should see your branch and commit:
7. Run the tests (if there are any)
Instructions for running tests are usually in the project’s README.md or CONTRIBUTING.md files. It’s important to make sure that you didn’t break anybody else’s work. If there are any tests that fail, your work will probably not be accepted until either you fix your code or change the test.
If there are no tests, well then… I guess you know what your next contribution should be ;)
8. Open a Pull Request (aka PR)
A Pull Request is the way to notify the project maintainers that you have some work that they should review and add to the project. You’re requesting that they pull your changes in.
To create one, go to your fork of the project, click on the Pull Requests tab, and click the big green “New Pull Request” button.
On the next screen, the “base fork” should automatically be the main project and the master branch. Leave them as they are for most projects. The “base fork” will include your name. In the “compare” dropdown, choose the branch name you were working on.
After you choose your branch, scroll down a little to review the differences between the master branch of the project and your branch’s work. This is a good place to catch anything you didn’t mean to commit.
Click the green “Create Pull Request” button. In the comments section, say a sentence or two summarizing the work you did. Include a link to the Issue you were working on. It might be helpful to mention something like “This is my first PR. Let me know if you have any feedback!” This way the maintainers know to give you more detailed pointers if something should be changed before it’s added to the main codebase.
Choose the big green “Create Pull Request” again to save your comment and finish making the PR. Leave the box checked that says “allow edits from maintainers.”
9. Expect changes and be patient
Next up, a maintainer or contributor will review your code. This is an important part of doing open source!
If someone asks you to make changes, don’t feel bad! It’s part of the learning process. Most maintainers will be so happy for the help and love having new people pitch in. Keep in mind it may take a little while before someone reviews your work. If no one gets to you within a couple weeks, it may be appropriate to @ a maintainer in a comment on your PR. Just remember that they are volunteers, so please be kind. A good way to figure out who to ping is looking at the closed pull requests and seeing who commented/did the merges.
10. Once your work is approved, it will be merged in!
Congratulations and thank you for giving back to the open source community :) This whole thing only works because of people like you.
X. Updating your fork
Ok, so what happens if you were working on a pull request or some time has gone by since you cloned the repository? Possibly the master code has changed a lot. How do you get those changes into your fork so that you’re working off the latest code? Grab the “clone or download” url from the project (the home repository, not your fork) and do these commands:
git checkout master
git remote add upstream the-clone-https-url
git pull upstream master
git push origin masterNow you can create new branches to do your work on. git checkout master switched to the master branch. git remote add helped you create a label called “upstream” that is connected to the url for the main project. So then when you “pull” the changes down onto your hard drive, you’re pulling the code that lives at the “upstream” url for the main project. git push origin master makes your fork (the “origin”) be synced up with what’s on your hard drive.
But what if you also have some work that was in progress? You’re working on code that’s out of date, so how do you combine it with the most up to date code? You need to do something called a rebase. A rebase takes your current branch and applies the changes you made to the branch that you specify in the command (in the example below, it’s master ).
git checkout your-branch-name
git rebase master
git pull upstream master
git push origin masterYou might have to resolve some merge conflicts, so here’s a resource to help you out.
