Contributing to Open Source

Hi All! With DigitalOcean, DEV, and Intel once again hosting Hacktoberfest to get people contributing to Open Source, I thought I'd share my experience from last year since it was my first time contributing. This is going to be aimed at newbies who have never contributed to Open Source. I'll be walking through the steps to clone down a project and submit it for review for the change to be added, as well as ways to make the process easier and less intimidating.

Firstly, just to set the scene and make sure we're all speaking the same language, Open Source just means that a project is open for the community at large to use and contribute to. It's a really amazing concept that allows developers to use software already created by others instead of re-engineering the wheel, which helps us to advance technology incrementally. There are a bunch of places you can view Open Source projects, but for the purposes of this article, I'll be using GitHub. For this to work, you'll need to have git installed on your computer and a GitHub profile, so go ahead and get all that set up if you need to, and then come back here when you're done.

Searching

Okay, now on to the rest of the article. How does one go about contributing to Open Source? Well the first step is finding a project that you want to work on. This isn't always as easy as it sounds, especially for newer developers (like me) who may not have the skills to jump into some massive undertaking and fix bugs or create full features, so what can we do? If you already have an idea of the type of project you want to work on, you can search it in the GitHub search bar, for example this year I know a particular company that I'd like to contribute to, so I can search the name of the company. If you don't know what to do, don't let that stop you! You can search for topics instead, I recommend "#beginner-friendly" for example. The "#" in front means your searching for a topic, like a hashtag, so you'll get the most reliable results.

Once you've searched, you'll be brought to a page that can be confusing and intimidating for people not used to it, but it's not as bad as it initially seems. It will give you repositories that you can review, as well as additional filters to narrow the results down. A good way to start though, is to look underneath the repository names and find one that has your topic, then you can click it to go to into a page devoted to just that topic, which is a much easier way to search.

Once you're in your topic page, you can filter by your preferred language at the top of the page and view relevant information. As an added bonus, it defaults to the Issues tab, which is what you're looking for in order to find a project. Now you can scroll down until you find an issue or feature request that looks doable and interesting and click it to go into the issue's page and look through details and notes.

Requesting the Work

Fork

Fork Button on GitHub

Great! Now you've found the perfect issue and you're ready to get to work...now what? Well the first thing you'll want to do is create a copy of the entire repository (or project). This way, no matter what you break, it won't effect the main project, this is just your version, so the pressure is off! This is super easy to do, just click the "Fork" Button at the top-right of the page and select your profile as the place to copy to and GitHub will do the rest. You'll know it's successful because at the top-left of the page, it will show the name of the repository, but it will be after your name now instead of the original author's.

Clone

git clone <your-forked-repository>

Now that you have your own copy, you can clone the repository from GitHub to your local computer. You'll need to open your terminal to do this (remember that you need git installed), and use the "git clone" command. First get the URL of your forked repository. Easiest way to do this is by clicking the green "Code" Button on GitHub and then the copy icon.

Then in your terminal, you type git clone git@github.com:dhintz89/Signal-Desktop.git (replacing the URL with the one for your project), and voila, you now have the repository locally on your computer.

New Branch

git checkout -b <new-branch-name>

You probably thought you were ready to start coding now didn't you? Well, we're not quite there yet, but we're close, I promise. All we need to do is create a new branch for the feature or fix we are going to work on. In your terminal, cd into your project directory and then type git checkout -b branch-name (replacing "branch-name" with your own branch name) and remember to name your branch name something descriptive because this is what the owner of the original project will see when you submit it back to them later on. This will create the branch and then check it out for you so you can get right to work.

Do the Work

Here's where you make your changes. Go ahead and build out that feature or fix that bug and save as you go along like you normally would.

Submitting your work

Commit Locally

git add .
git commit -m 'commit message'

Once you're ready to submit your work, you'll commit the changes to your local git record by typing into your console:

git add .
git commit -m 'commit message'

Remember to make that commit message very descriptive so the project maintainer will know exactly what they are getting!

Push to GitHub

git push --set-upstream origin <your-branch-name>``

Now that you have your code committed, you can type git push --set-upstream origin branch-name in your terminal to push everything you committed locally to your GitHub repository.

Set the Original Repo as your New Remote

git remote add upstream <original-repository>

To submit your changes, you'll need to set up your repository so that it's able to push changes to the original one. Type into your terminal git remote add upstream and then the URL of the original repository (the one that you do not own). Example: "git remote add upstream git@github.com:signalapp/Signal-Desktop.git". If you type git remote -v` you should now see four lines printed out, 2 starting with "origin", and 2 starting with "upstream".

Sync Your Repository with the Original Project

`
git fetch upstream
git checkout master
git merge upstream/master
`

While you were deep in the weeds making your changes, someone else may well have been doing something similar to the same project. What could happen if you now submit your change is that you may submit code that conflicts with their changes, and that's bad news. To avoid this, you'll just make sure that you sync your code with the current main project in order to copy over any recent changes. Do this just before you're ready to submit your code to the original project's maintainer.

To do this, type into your terminal git fetch upstream and you should see a similar output to this (this will be at the very end of the output:
`
From <original-repository-name>
[your-branch-name] master -> upstream/master
`
Now, switch to your Master branch: git checkout master and merge your Master branch with the original Master branch: git merge upstream/master and now through the magic of git, everything will be up-to-date and ready to (finally) submit.

Create Pull Request

New Pull Request Button in GitHub

It's finally time to submit your changes! Go to your repository in GitHub and click the "New Pull Request" button:

Then select which branches to merge, this is usually the Master branch on the left (original repo) and your newly created branch on the right (you forked repo), and GitHub should tell you that you are "Able to merge" assuming that you properly followed the last step and synced up the 2 repositories. Now just add a title and any comments you think are important and click the "Create Pull Request" button.

Celebrate!

Aaaand you're done!! Time for a well-deserved break.

I know this seems like a lot to handle, but the workflow starts to become second nature after a while and really, it's all set up to make sure that you can't accidentally ruin someone else's work to and take that scary pressure off of you. And contributing to Open Source has been one of my favorite ways to improve. You often get direct feedback and suggestions from real engineers about your specific code, as opposed to some hypothetical learning exercises, plus you get to feel good about having helped to build something cool! So go out there and explore, try a few simple contributions, even just going in and adding in some notes or a missing README is often extremely appreciated. You will become a valuable part of the Open Source community in no time.

Good luck and have fun!

And for a better look at the technical workflow, read this amazing article by Lisa Tagliaferri, it has more detail and taught me pretty much everything I know about it.