Contributing to a Repository

Today I contributed for the first time to a public repository. I don’t know what took me so long but the thought seemed scary for a long time. But today everything was different. I saw Tour of Rust in the top 3 on Hacker News.

I discovered here and there typos and other small things and on some page I just got curious to take a look into the repository and ended up making 4 pull requests (PR). All of them being accepted an merged.

What a lovely experience! I will try to summarize what I’ve learned.

What to Contribute to

I heard a lot that you should contribute to things that you use. This was definitely the case for me here and it helped tremendously. I knew the scope of the project and most of its parts so I could feel comfortable that I was not out of place here.

I think people underestimate the power of contributing to small projects. Everyone wants to contribute to big frameworks like Ruby on Rails, Django or Laravel or other pretigious projects like React or Redux, but the reality is that this is fairly difficult. If you want to get your feed wet in open source culture it might not be the best to start witht the biggest projects.

A lot of projects have barely any support and search for contributors try to get into the game there! Maybe you use a little npm package or some niche command line tool. These are great places to start!

Setup

Once you found something you would like to contribute to it is time to dig into the setup. Somehow you need to get the project to run locally on your machine.

The first thing to do is to fork the repository on Github, Gitlab or some other cloud repository service.

Next you do the same thing you do with most repositories. You clone the forked repository:

git clone https://<repository-service>/<username>/<repository-name>

Now that you have the repository on your machine you need to find out how to work with this project. You will need to install dependencies and try to find out how to get the thing up and running. In case there is no good documentation available take a look at available script or dependencies files like package.json, Gemfile or Makerfile.

Really, don’t get frustrated. It took me ages to figure out how to run Tour of Rust locally, even though it is not even a complex project (no offense Richard). I just installed the wrong dependency and there was no documentation on how to correctly set up the project. Just continue looking and see it as a little puzzle. If you can’t find out how to run the project after more than a day you should reach out to the maintainers or ask on Stackoverflow.

Making changes

You figured out how to run it and you are ready to make your changes. Bravo! I would argue the hardest part is done. Most open source project creators don’t realise how freakishly hard it is to get their projects up and running.

Before you go wild set your fork up to be in sync with the original repo. Stefan Bauer explains how this works in detail in his excellent blog post “How to keep your Git-Fork up to date”.

What you want to do is add the original repository as a remote upstream like this:

git remote add upstream https://<repository-service>/<username>/<repository-name>

With this you can use git fetch upstream to keep your local version up-to-date. After fetching create a new branch for your changes git checkout -b <descriptive-branch-name> and get going! While making changes be careful to give your commits good messages so that the person reviewing your changes understood what you did. The site conventional commits offers a good specification for this.

When you are done with your changes push them to the remote repository like this:

git push remote -u origin <your-branch-name>

Creating a pull request

Now that you pushed up your changes go back to the original repository and create a pull request. There will be a dedicated button on top of the page for it after you pushed your changes to your fork.

The pull request message and title and tremendously important for the success of your changes. If you don’t explain properly what you did and why you did it people will just ignore your work which would be a shame. Therefore take some time and write a nice message. You can even take a few lines and thank the creator(s) for the project. If you did something with a visual impact add pictures or gifs! Everything that helps the reviewer ot understand what you did will be greatly appreciated.

It may take some time but after a while your request will be reviewed and maybe even merged. Don’t be too impatient and if after a while no one reacts try to make your PR more atractive. Maybe add some labels and double check that you followed the project’s guidlines (if they have any). Worse comes to worse try to reach the maintainers by email or on Twitter.

Becoming a part

Everyone speaks about open source and its impact. How everyone should contribute. I totally agree but we need to get better in giving people the information they need to participate easily. But I can tell you no matter how small the project is, it is a wonderful feeling to see your own code in someone else’s repository.

And just like this I have become a member of the open source community. Yay!