Sunday, April 15, 2018

My First Open Source Contribution

Today was a pretty special day for me, professionally. I opened up and merged a pull request for Mapstruct, which is a pretty popular Java Bean wire-upper. If you program in Java and haven't heard of/used it, I recommend checking it out. In fact, I could probably do an entire post on it but I'll save that for another day.

This post is gonna be about how you, the neophyte developer can do what I did and get your first open source contribution. Before we delve into that though, there's a question worth asking:

Why bother in the first place?

The answer to this question has many facets, but I can almost guarantee that at least one of them will appeal to you. First off, open source projects only exist because engies are willing to spend some of their precious free time working on them. There's no money to be made and no reason beyond the community itself for an open source project to grow and improve. So it's kinda like recycling. If everyone does their part, everyone wins.

That leads to another reason why contributing to open source projects is dope: the people. Odds are, you work with a static group of people at your job. Obviously, if you freelance or consult, you might see more of a varied set of coworkers, but for most of us, we have a "9" to "5" and we spend most of our time working with our teammates. When you contribute to an open source project, you're getting the opportunity to work with people that are sometimes on the other side of the world. Being exposed to other rhythms can teach you a lot of really useful interpersonal skills while also teaching you how to work remotely.

In terms of professional development, one of the best reasons to contribute to an open source project is that it will almost certainly expose you to new facets of programming you haven't been exposed to. Regardless of how many projects you've worked on at a given job, there's a closed set of skills you will learn at a place because you aren't programming to learn (at least primarily), you're programming to solve a specific class of business problems. Working on an annotation processor is indescribably different from building APIs or data pipelines. And that new problem set will teach your brain things it wouldn't otherwise learn. And that will make you a better developer.

Another great reason to contribute is that you can earn some serious street cred. When people from other companies are looking at your resume while you stealthily look for that next job, they will at the very least notice open source contributions. If they really want to see what you're made of, they may even look at code you wrote. The nice thing about these pull requests is that these projects are open by definition. Most companies keep their code buttoned up very tightly, and so it can be difficult to show off your skills outside of personal projects.

So as you can see, this non-exhaustive list of reasons to write for an open source project is already getting pretty long. So now onto the question at hand. You're a newish developer and you've never contributed to an open source project before. Where the heck do you start?

Start with what you already know.

It might sound silly to say, but starting with a library/tool that you're already comfortable with as a user is easily the best way to get your feet wet on open source contributions. Take me for example. I've only been developing in Java for a few months, but because the project I'm working on heavily leverages Mapstruct (again, I definitely smell a full post on this topic in the future), I've had to become pretty familiar with what it does, how it works, and crucially, what could be made better about it. With this small amount of experience in hand, you can move on to the first step.

1. Check out the project's git repo and take a look at the open issues.

Easy enough. Go over to git and see what issues the project runners have deemed worth doing. The types of issues you're looking for are ones that involve documentation sprucing (don't roll your eyes at me it's important and also to write good docs you need to understand the code so just do it), enhancements, additional tests, or minor feature requests. Mapstruct does a fantastic job of also tagging issues that are "good first issue"s, which was how I found the issue that I ended up fixing.

As you're pruning through the open issues, it's always a good idea to start from the oldest and work your way forward. Often times, really exciting features will be scooped up quickly by people who already know what they're doing, but more simple work will be left behind. That's the kinda stuff you want. Additionally, sometimes a new contributor will say they're going to take a crack at something, only to walk away from the issue. If an issue has comments on it, people will often skip over it because they assume someone is already looking into it. Take those orphaned issues as opportunities to do the maintainers of the project a favor by closing something that's been open for a while.

2. Ask. Questions.

This advice applies to almost everything, but it's especially true here. Don't be afraid to ask questions even though github is public and people will see what you say. If it's your first PR, own that! By letting the owners know that you're green, they'll know to be more expository and clear with their explanations. Otherwise, they'll just default to how they usually discuss the project. And since they're experts, there's a good chance they'll talk right over your head. However:

3. Don't waste people's time. Do lots of digging, testing, trying, build breaking, and failing before you ask for help.

One of the most inconsiderate things you can do to a person who knows more about a thing than you do is approach them for help without having done some diligence beforehand. This is another piece of advice that, honestly, extends beyond open source contributions. If you're going to impose on someone's time, make sure that you and that person can cover things as efficiently as possible. That means doing everything in your power to investigate before you start peppering people with questions.

4. Squash all those silly commit messages

Full disclosure: I think funny commit messages are the funniest things in the entire world. However, when contributing to something external, it's nice to have messages like "added tests to cover new annotation" instead of "if this build fails again I'm going to move to Bhutan." One thing I like to do is open the PR with exactly one commit. The message for that commit can be something similar to the title of the issue. Then, throughout the PR process, you can add more commits if necessary. This is a relatively minor thing, but if like me, you tend to commit very often, it might be the sorta thing someone will yell at you about. Read up on how git rebase works and you'll be fine.

So that's about it!

It's really not to hard or scary or intimidating to get involved in open source projects, and only you can decide when you're ready to do it. Once you do, make sure you deliberately set time aside on the weekend or after work to actually do the thing though. Otherwise you're likely to just think about doing it instead of actually doing it. Leaving a comment on an issue saying that you're looking into it can be a dangerous psychological trick because sometimes just leaving the comment will convince you're brain that you started making progress. Have some code written before you announce your plan of attack.

Happy contributing! 

No comments:

Post a Comment