Chris Noring for ITNEXT

Posted on Oct 28, 2019

How YOU can contribute to OSS, a beginners guide

#showdev #beginners #tutorial #opensource

Follow me on Twitter, happy to take your suggestions on topics or improvements /Chris

TLDR; this post hopes to show you, who are curious about OSS, HOW to get started, what git commands you need to type and some concepts you should know about. This is detailed, with pictures :)

In this article we will cover:

Rules and regulations, let's talk about things you should be doing for OSS as well as enterprise development
Getting started, this will cover things such as learning to fork the repository, create a local branch, add code and finally raising a PR, a Pull request
Dealing with change requests, you will have contributors asking you to change things, such as title, or what commits you have or even how to squash them to one commit, it's all covered here

So you are curious about how you can contribute to open source? Good, that’s a nice mindset to have. Things that are open source can be used by all of us so YOU spending whatever extra cycles you have is a very nice thing to do and can be quite fun and educational as well.

Rules & Regulations

Contributing to Open Source does come with some rules though, rules that are there for a reason. Imagine a bunch of developers all wanting to contribute, we need to have a way to make sure that their changes are done in a responsible way. Responsible might mean things like:

Linting, Code adhering to the linting rules or in other ways following some style guide
Tests, there are updated tests or added tests that go along with your suggested change
Commits are either squashed or divided up into many small commits, where every commit only changes one thing. For this to work well each commit should follow some kind of naming standard like this, for example, Semantic commits

Getting started

Most projects won’t let you push your branches directly toward the repo but you need to instead to fork the repository. A fork is simply a copy of a project and means you don’t directly affect the project that you want to help out with. This leaves room for you to experiment freely on your forked repository. So how do we get those changes to the real repo? For that, we need to create a PR, a pull request. Then we just need to get the PR to pass the reviewers and their CI ( Continuous integration) system and BOOM, you can call yourself a contributor. Let’s write down the exact steps we need to take and show each step in detail:

Fork the repository
Create a branch locally
Add code and optionally tests on your local branch
Commit the changes to your local branch
Push code and raise a PR

Fork a repository

This step is quite simple. Just click the Fork button and it will create a copy of the repository on your GitHub account.

Create a branch

So now we create a branch locally for our code. You can create a branch and check it out in one motion:

git checkout -b feature/name-of-my-feature

Now you are ready to change whatever you need in the code.

Test

You should, preferably, before you start coding, think about how you will test your changes, do you need to add an integration test or a unit test? Check your specific project on how you build and run that library/framework and especially how to run the accompanying tests. Once you start adding the code you will see if any tests break because of it. If no tests break you are either lucky/good or you might need to add some tests yourself. Make sure you look at how other tests are written in the project in terms of naming and code style.

Committing

My recommendation here is that you don’t add too many changes at once. Have small focused commits that are nicely named, according to what they do. For example:

feat: adding pagination to product list

test: adding tests for pagination of product page

Push changes

Once you’ve achieved what you intend to achieve, it’s time to push the changes. You can do so by typing:
git push origin master

Raise PR

Here you go to your fork on GitHub and you select the New pull request button.

Once you select that you will come to the next page looking like this:

Above we need to select our repository on the right together with the pushed branch. Then we need to hit the green button, that is you have not already created the PR, it should say Create new pull request. At this point, you can give your PR a name and you should also see if there are some checkboxes you should be checking to tell the maintainer what your PR is about. Once your PR is created the button will change its text to View pull request. Clicking this button will take you to the actual pull request in question.
Now the PR lives on the actual repo that you are trying to change and should look something like this:

Pay attention to the comments on this page as core maintainers will tell you if something needs changing. Also, the CI system might tell you if something is wrong and will provide you with hopefully a useful error message:

Dealing with change requests

This is a process that might take a few iterations to get it right. It might be things like:

title, your PR title needs changing
hard to see changes, your commits are not small and focused and need either splitting up or need to be squashed if there are too many of them
failing test, a test fails ( you should have caught testing locally but shit happens :) )

Change PR title

The reason for this change is that your title might not conform to a certain standard. Make sure you check examples, provided in the repo, of what this should look like.

Squash Commits

At this point, a maintainer has said that a number of your commits could have been made into one commit. They will usually tell you which ones should be grouped together. Squashing means a number of commits will now be replaced by one commit. So how do we do this? This link will tell you all the steps but let’s go through them. Let’s start with the first command:

git rebase -i master

At this point, you will be presented with the following:

we can at this point see all our commits. All commits will start with pick followed by a commit ID and then the commit message. The commit you want to keep you do nothing with, i.e you keep the pick keyword. In this case, we want to make sure the latest commit gets squashed into the top commit. To do that we change the second commit like so:

Above we pressed i to end up in insert mode, cause this is VIM, yes I know how to exit ;) Now we have done the changes we wanted so let’s save this. Press Esc to leave insertion mode and then type : and type :wq this will write the changes and quit VIM.

NOPE, what you thought it was that simple to exit VIM? ;) Now you are getting a page where you are told to adjust the commit message. It will consist of all the commit messages like so:

The character # will be ignored so adjust the other text, most likely you want to keep the first commit message, like so:
We press i for insertion mode and we edit the text so we have this:

Now let’s try to exit VIM again with :wq . This time we did it and it should look like so:

Now we need to push this to the repository. We need to force push it so we type:

git push -f

Looking at our PR it now looks like so:

There is only one commit, success.

Rename you commit

Ok, so the maintainer seems more pleased this time. However, they want you to rename your commit to feature: adding install instructions. Ok then, we can do that. To accomplish that we use the following command:

git commit --amend

This gives us the chance to update the commit message and it should look like so:

You know the drill by now i to enter insert mode and change the message appropriately:

Then hit Esc to exit insertion mode followed by :w. Now, check git logs that your commit has been changed accordingly:

Ok great, our commit has changed names, at least locally. Let’s push it to our repository because you changed this locally:

git pull // make sure you do this one first
git push

Ok, so at this point, your repository will create a merge entry in your git log which effectively means you will have two entries. So let’s begin the crazy circus again with:

git rebase -i master
// change some commits to squash
git push -f

Finally, we have this:

Summary

Hopefully, you have gotten your first PR merged in by now. Congrats you are a contributor, you just helped the entire coder community. Did it feel like a lot of work? Well, there are OSS maintainers out there that have this as a real job and the work you do is hopefully used by a lot of devs out there so you should be glad that there are few hoops to jump through to ensure quality.

Top comments (11)

Johannes Lichtenberger • Oct 28 '19

Awesome description, will link it in my OSS-repositories 👍

Chris Noring • Oct 28 '19

Thank you, Johannes :)

Johannes Lichtenberger • Oct 28 '19

You're welcome :-)

Evan • Oct 30 '19

Thanks for the article! I work for a small engineering team (~15). I want to push our team and organization to open source (ie. contributing to OSS projects we use and open sourcing some of our tools). My initial thinking was to start with some education and the important of giving back to OSS.

What are some methods or tips for getting buy in from the team and management for OSS?

Chris Noring • Oct 30 '19

it makes your workplace more attractive to developers they might want to hire, it shows it's a fun place to work
it's also a way to try ideas out and have developers on your company start collaborating that might not be on the same team
software developed might get additional help from the outside through PRs.. that might lead to finding people you want to recruit or work with for freelance gigs..

In short:

it makes you look good to help finding talent
promotes more cross-collaboration across teams in your company
the software developed might benefit both your company and others, and you get external help to make that software even better
it might make it a more fun place to work, especially if devs are allowed to spend x hours on it per week, so it might help to retain staff.