Step-By-Step Guide To Your First Successful Open Source Contribution

If you’ve never contributed to open source (and don’t know how to get started), here’s YOUR step-by-step guide. Read time: 10 minutes.

Want To Learn More?

I'm making an "over-the-shoulder" video course on how to master open source and turn that into career security. Sign up to be notified when it releases in a few weeks.

arrow-circle-right

Here’s what we’re going to cover:

  1. Removing Blockers to You Actually Contributing
  2. Picking a Project That’s Right For You
  3. How To Prep For Your First Contribution
  4. How To Practice On a Real Project With Real Issues – Risk-Free
  5. Doing The Pull Request
  6. Handling Criticism
  7. Next Steps – Use Open Source to Get New Jobs

Getting Started

You’ve heard that contributing to open source is great for your career.

That’s true.

Your contributions are portable proof that you have both attributes needed to be a successful software developer:

  • You have technical skills
  • You have people skills

Besides that, it just feels great.

But (and here’s the problem) it’s hard to get started. Open-source has its own foreign language. In addition, if you’re not familiar with git version control, it’s even worse.

If you don’t know how to use the git command line, fix that now. It’s not hard. Here are two resources you need:

Open-source needs you, and in a way, you need open-source. I’ve already mentioned it, but the satisfaction is just the start. Keep at it, and you build a reputation that leads to true job security as you can eventually be seen as an expert due to your full commit history.

Removing Blockers to You Actually Contributing

Not knowing where to start isn’t your fault, and we’ll get you unstuck now.

Any of these sound familiar?

  1. How or where do I get started?
  2. I don’t see many beginner issues.
  3. Lots of projects look too intimidating or complex.
  4. What if I commit to a bug fix and then can’t do it?
  5. What actually is the step-by-step process for a contribution?

Let’s address each one.

How or where do I get started?
Keep reading. I address this step-by-step.

I don’t see many beginner issues.
You can ignore this concern. It’s not real. Suspend your disbelief if you need to, but when you follow the plan I’d laid out below, this doesn’t matter.

Lots of projects look too intimidating or complex.
It’s true. Some issues will be beyond you. However, most are not. They only look like that as you haven’t dug into the project and run the code and learned how it works. Keep reading, I address this too.

What if I commit to a bug fix and then can’t do it?
You contact the project maintainer and tell them you will not be working on that bug fix anymore. The project maintainer will be thankful that you didn’t just disappear and they can now have someone else look at that issue. No problem.

What actually is the step-by-step process for a contribution?
Now, for that step-by-step instruction…

Picking a Project That’s Right For You

I’m sure you’ve heard the standard advice, “work on the open-source projects you already use.” Not the most useful advice, in my opinion.

Instead search google for “top open source projects in [language or framework]”. Don’t overthink what language to use. Go with what you know best.

When looking at projects, look for bigger ones that have lots of documentation around contributing and working with them. You want to work on a project where the maintainers are active and used to working with beginners to open source.

Restated, if the project you are looking at doesn’t have excellent and clear docs around how to contribute, pick another project.

Want To Learn More?

I'm making an "over-the-shoulder" video course on how to master open source and turn that into career security. Sign up to be notified when it releases in a few weeks.

arrow-circle-right

How To Prep For Your First Contribution

Set up your development environment, if you haven’t. (Get Visual Studio for working on DotNet projects; get Eclipse for working on Java, etc.)

Next, fork the repo to your GitHub account.

Then clone it down to your development machine.

Next, look at the Contributing.md file and find the getting started doc.

What if you don’t find one?

Double check all the documentation, but if you don’t find one, you have found your first contribution opportunity. You should make a “getting started” doc for the project. Side note: most projects need help with documentation in some capacity.

Before starting, verify the maintainer is interested in the documentation you want to add. The best way to do that is to open an issue stating that there isn’t a getting started doc.

If the contributor agrees that this is something that would be of value, boom! Dig into the code, debug through it, document what you do, and submit a pull request with the doc.

But I’m getting ahead of myself.

So, you’ve got the code and you know how to use it now (either using the existing getting started doc or via essentially creating the doc yourself), now you are ready.

How do you feel?

If you’re fully confident jumping in now, go find an open issue, start chatting with the maintainers about taking it, and start coding.

But what if you’re not feeling quite ready yet?

How To Practice On a Real Project With Real Issues – Risk-Free

No worries if you’re not quite ready yet. Here’s how to bootstrap your own self-confidence right now.

Look at the closed issues on the project you’ve chosen.

Then, pull the code before the bug fix was checked in. To do that:

  1. Click the link of the commit that fixed the bug.
  2. Copy the first 6 letters of the commit SHA
  3. Go to the list of all commits
  4. Find the commit in the list, and copy the SHA of the commit just before the bug fix
  5. Execute the git checkout command with that shaw. You’ll now have the code pre bug fix, and you are ready to do your own fix. (see video below)

Repo the bug per the issue yourself. (If you can’t, select a different closed issue.)

Then, practice fixing the bug.

No pressure. You are practicing. Even if you end up over your head (not likely), it doesn’t matter. Plus, you can look at the solution to see how the fix was coded, if you want. (The commit to the master branch that fixed the issue.)

In addition, you can do this kind of practice as much as you’d like.

And now, you are ready.

Doing The Pull Request

The steps are the same as above.

  1. Fork the repo to your GitHub account (because you don’t have permission to make a branch on their GitHub account)
  2. Clone the repo to your machine
  3. Take an open issue or open a new issue (if you are contributing something that isn’t a bug fix)
  4. Make a branch for your work
  5. At the same time, you are chatting back and forth with the project maintainer about the work you are doing.
  6. Lastly submit the pull request. For a walk through with screenshots, have a look here: mechanics of making a pull request

When the contributor accepts your pull request, congrats! You are apart of the open source community!

Want To Learn More?

I'm making an "over-the-shoulder" video course on how to master open source and turn that into career security. Sign up to be notified when it releases in a few weeks.

arrow-circle-right

Handling Criticism

Not everything is perfect in the OSS world. You are dealing with normal humans. Mostly volunteers too.

There will be criticism. By making a pull request, you invite public inspection. Not everyone is going to love what you’ve put out there. The good news is that some feedback is useful, and you’ll grow as a coder. However, some will be toxic, and you need to be ready and understand that upfront.

In a similar vein, you might never get a response to your pull request. This is far, far less likely on a mature, community-maintained project. That’s why you were steered towards the larger projects above.

But enough of the negative. Let’s look at the big picture.

Next Steps – Use Open Source to Get New Jobs

Want to build up a reputation?

Making a single contribution and nothing more is no good.

Equally bad is very sporadic contributions.

To become known and respected, you should focus on one tech stack and be active with contributions.

You may want to even start your own open source project too.

Really though, the key here is simple. Be consistent. Stay on it. Keep making pull requests. Develop deeper relationships with project maintainers. It’s that simple.

When you do, you’ll begin to notice two things:

One, recruiters will contact you because of your GitHub profile (not just because of your LinkedIn account), and these are higher quality inbound connections as they already can see what you can do.

Two, when you do outbound networking or looking for a new job, you can point people to a GitHub account that proves you work hard, you know your stuff, and you are a team player (due to getting all those pull requests accepted). Boom! Money.

Want To Learn More?

I'm making an "over-the-shoulder" video course on how to master open source and turn that into career security. Sign up to be notified when it releases in a few weeks.

arrow-circle-right