Tips for getting started with open source

The Hacker Ethic

The FOSS (Free & Open Source Software) movement is the modern incarnation of something older: The Hacker Ethic.

In the early days of computing, computers were extraordinarily expensive and inaccessible to most people. They could only be operated by teams of trained professionals. But at MIT, a group of enthusiasts were sneaking in at night and stealing time on the computers. From these hackers came gifted programmers and engineers, and eventually they were the ones who got to make decisions about how software was written and how computers could be shared. It’s largely thanks to the passion and vision of these individuals that we have personal computers today.

These early hackers did not care about money, copyright, or fame. They just wanted to share the magic of computers with as many people as possible, to realise together all the possibilities opened up by these new devices. They would write programs on pieces of paper that were stored in a drawer next to the shared computer, and anyone else was free to use or improve upon their work. The joy of programming and the satisfaction of having created something was enough for them. Information wants to be free, and the hackers wanted to help it.

The Hacker Ethic is alive and well in the FOSS community, and understanding it may help you to understand the thinking of other people you will meet on your journey. If you’re interested in learning more about the Hacker Ethic (and about the history of the software industry) then I recommend reading Steven Levy’s excellent book Hackers: Heroes of the Computer Revolution.

A word on politics

If you’ve read other articles on open source, you might’ve heard stories of projects ruled by internal politics.

Doubtless there are some projects where this is the case, but in my experience they are rare. Most projects have some degree of politics, yes, but it’s usually subtle enough that it won’t impact a casual contributor. If you become deeply involved in a project then the politics might become a concern to you, but if you’re just stopping by you can probably ignore them. For example, I’ve seen articles recommend checking contributor lists before you submit a PR, but I find this wholly unnecessary.

I think the key is to be polite and positive. If you are submitting a PR that changes someone else’s code, respectfully explain the improvements your code has made. If you are opening a bug ticket, don’t insult the person that introduced the bug. Your goal when interacting with a project should always be to help, whether you are helping them by alerting them to an issue or directly helping to fix an issue. As long as people can see you are helping, you will probably get a good response.

Work on things that impact you

It’s possible to search for “Help Wanted” or “Good First Issue” tags on GitHub, pick a random project, and try to contribute. But I wouldn’t recommend it unless you’re a seasoned open source contributor; probably not even then. After finding an issue that interests you, before you can start work on it you still have to figure out the purpose of the project, the context of the bug, how to set up and use the project, etc…

I think the best way to start contributing to open source software is to first start using open source software. Maybe you’re already using open source, in which case that’s great. Otherwise, try to make it a mindset that when you need to solve a problem you check for open source tools first. Make open source your default!

Once you are using lots of open source software, you will inevitably run into bugs, or bad/missing documentation, or you’ll see that there’s a simple feature that could be added that would make life so much better. Don’t just wish that things were better, with open source you can make them better.

Aim for projects that aren’t too big and aren’t too small

Large projects can be very complex, making them difficult to contribute to. Without a lot of experience with the project it might take hours to even find the file in the project that you need to change, and it’s hard to predict what obscure functionality your change might break. I am (still) scared of large projects and (while I’ll submit bug reports to them) I generally steer clear of submitting code changes.

Tiny projects might also not be ideal for a newcomer. Since they often only have one maintainer, response times may be very slow, or the project might be completely abandoned. There aren’t likely to be many resources on how to contribute. Plus it can be a bit of a lucky dip as to how friendly the maintainers are.

I’ve had the most success contributing to projects somewhere between the two extremes of sizes.

Imposter syndrome

It’s easy to look at all of the amazing creations of the open source community and feel like you could never do something like that. I believe that this perception is caused by selection bias in the open source community.

If you’re working for a company there will always be people who aren’t that passionate about programming, they just want a paycheck. They might do the bare minimum of work, or they might just try to get the job done without caring about code quality. Comparing yourself to these people can make you feel better about your own abilities. But in the open source world pretty much everyone is passionate about software, so comparing yourself to others will make you feel worse. Maintaining your self confidence can be a mental battle.

You might see people like John Carmack and Jon Skeet and think that you will never be able to approach that level. But the reality is that most open source contributors are normal programmers, and the only reason big projects can be achieved is through collaboration. Maybe you won’t become a household name, but you can definitely contribute meaningful changes and there will be at least some people who appreciate your efforts.

Be aware that 58% of tech workers report that they experience imposter syndrome, even (and sometimes especially) if they have many years of experience working for prestigious companies. Feeling inadequate is very common in the software world, but it’s usually not justified. In fact, due to the Dunning–Kruger effect people who are less experienced might have less feelings of inadequacy.

If you can learn to recognise when your negative thoughts are caused by imposter syndrome, this knowledge can help you to overcome your self-doubt.

Start small, build your confidence

When you’re starting out, try to stick within your comfort zone. You don’t want to invest hours into a contribution only to have it rejected because it doesn’t fit with the project’s direction, or doesn’t live up to their standards.

Maybe filing a bug report isn’t your idea of “contributing to open source”, but it’s more than most people will do! If you provide a bug report that clearly explains the problem and gives detailed steps to reproduce it, or a minimal, reproducible example then you are helping a lot. If you find a workaround, put that in your bug report too, you might help other people experiencing the same issue.

Many articles about “getting started in open source” also recommend starting with documentation. This is a great option if you’re good at writing. If there’s missing documentation, read the source code or perform your own experiments to work out the behaviour. If you noticed the documentation was missing then chances are you need to know the behaviour anyway, so once you find it out just write up whatever you discovered.

Understand the project’s communication channels

Most modern projects seem to be centred around GitHub. Bugs are submitted as Issues, discussions take place in issue threads, and improvements are submitted as Pull Requests.

But different projects use different methods of communication. Many projects use IRC for conversing about the project, and their maintainers might prefer that you got in touch there instead of via a GitHub Issue. Some projects have a GitHub repository that is purely a read-only mirror of their real Git repository, hosted elsewhere.

If you try to contribute in the wrong place you might just be yelling into the void.

If in doubt, ask

If there’s a bug that you know the perfect way to fix, go ahead and submit a pull request. But if you’re not sure of the best way to solve a problem, make a bug report and say that you’re happy to work on it but you’d like some guidance.

If you want to add a new feature, you should usually ask about it first. When I review contributions to projects that I am involved in, getting a pull request for a new feature out of nowhere puts me in a bit of an awkward position. Someone has put work in to developing this feature, but what if it’s not aligned with the goals of the project? I’d feel bad to reject it, so I feel pressured to accept it. These types of contributions almost always require some adjustments to make them fit the project. If the contributor had asked for guidance beforehand we could’ve discussed implementation details upfront and saved some time.

Maintain backwards compatibility

Be careful that your new feature (or bug fix) doesn’t break things for existing users. The safest way to achieve this is to place your change behind a configuration option and ensure that the default value of this option preserves the current behaviour.

Backwards compatibility isn’t always possible, practical, or desirable. If your change isn’t backwards compatible, don’t try to hide that. Mention in your pull request what situations your change might cause issues in and why you think that’s okay. Or, better yet, ask about it before you even submit your PR.

Make your code fit in

If the project has a style guide, make sure you follow it. If the project has linting settings, make sure you adhere to them. If the project includes unit tests, run them before submitting your change.

Make sure your code follows the same standards for indentation, line endings, spacing, bracket placement, naming, etc… as the existing code.

Be patient

It might take several days or weeks for someone to review your change. Many people do open source in their free time, and many of us have busy careers that encroach on that free time. Unless the project is abandoned, they will get to your contribution eventually. Do not send the maintainers emails or any other out-of-band communication unless they specifically invite you to, this is considered rude.

Once your contribution has been reviewed, it is most likely that the reviewer will request some changes. This is normal, it doesn’t mean your code is bad. Try to be receptive to their feedback and modify your code in response to it. You are allowed to disagree with them (and to explain why) but try to avoid getting into an argument, keep it respectful. They are looking after their project, they need to be strict about what changes are allowed in.

I consider myself an experienced developer, and I have been asked to make changes to my pull requests more times than not. Similarly, when I review pull requests I usually request at least one change be made to them.

Leverage any resources the project makes available to you

Many larger projects have a CONTRIBUTING.md file in them which provides guidance for how to structure your branches, how to build the project, how to run unit tests, etc… If such a file is present, make sure to check it out.

Some projects have entire documentation dedicated to developers/contributors in addition to their API/user documentation. This can be an invaluable tool for understanding the inner workings of the software.

I’ve recently noticed that Gatsby offers free one-hour pair programming sessions for non-commercial use, which you could use to get some help with your contribution. Maybe some other projects offer similar things.

Search around to find out what resources the project you are contributing to offers.

Conclusion

That’s all the tips I have for you today. I hope that you found at least some of them relevant. And on behalf of the open source community, welcome!