Starting an Open Source Project

After a year of building and maintaining boardgame.io on the weekends, I’ve learned some things that might be useful to some of you thinking about starting open source projects on the side. Here are some thoughts:

1. You don’t have to be an expert.

This is something that often holds people back. The point of an open source project isn’t to show off your abilities to the world. The point is to get contributions from the community in the form of ideas, bug reports and code. These will shape the project, and depending on how you manage it, can take an early work-in-progress prototype to something much larger.

When I first started boardgame.io, I was quite new to a lot of web technology like React, Redux, socket.io and NPM (having mostly written C++ code prior to that). However, the project was a great learning experience for levelling up on frontend technology and I’m no longer afraid of Webpack configs (OK, maybe just a little bit).

2. Document everything.

Spend as much time on documentation as you are on code. I can’t emphasize this enough! If you want your project to be used by a lot of people, make sure that the docs cover everything from how to get started (tutorials) to guides for more advanced users.

There are many excellent Markdown based documentation starters like GitBook, Material for MkDocs and docsify.js that you can use for this.

Make sure that you also have a separate section for contributors. You should highlight your expectations here and also include pointers to how they can find things to contribute to.

3. Test everything.

Strive for 100% test coverage wherever possible. By this I mean that every line of code should be executed by at least one test and every conditional should be tested on both the true and false branches. Not only is it therapeutic to see that perfect test score, but it is particularly important for open source projects that are meant to receive contributions from the internet. If you have good test coverage, you can confidently receive contributions without worrying about code breakages.

If you are coding in JavaScript, Jest can collect coverage statistics (see my other post about this). You can have your tests run automatically whenever you push your code to GitHub by connecting a Continuous Integration service like Travis, CircleCI or Semaphore. You should also consider including a badge on your documentation page to display your test coverage and current build status. This will generate confidence in potential contributors that you maintain a high quality codebase that is easy to modify.

4. Get people involved.

The key to scaling out progress is to get others involved. This is why it’s a good idea to get something out even if it’s just an early prototype that you aren’t particularly proud of yet. As long as you are able to communicate your idea clearly, people will get excited about it and jump on board.

Contributions will come in the form of code fixes, bug reports, documentation typo fixes, and feature requests. All of these are extremely valuable, and you should cultivate a friendly community that’s open to feedback from anyone, regardless of how experienced they are.

At this point you will start to realize that more of your time is spent guiding and directing. These are very good skills to develop, and an open source project is a great place to practise them.

5. Productivity tips.

There are many projects on GitHub that have a few initial commits and are then abandoned (probably because the author got busy or bored). The key to success is to to stay productive on your project for months and years.

One strategy that I’ve found helpful is to pace yourself. This sounds counter-intuitive, but resist the urge to spend a lot of time on your side project. Document your ideas for features on little notes and only start coding when you have a clear idea about what you want to build. It’s also OK to leave work unfinished that you can get back to the following week.

Also, don’t feel obliged to implement every single feature request that comes in. You are serving the community by volunteering your time on this project. While you must strive to serve your users well, they are not entitled to your time. Saying no to certain requests will become key to staying productive on your current todo list.

An open source project is a great way to improve your skill as a programmer. It will also help you pick up other skills that will help you in your professional career. As project maintainer, you will get to practise leadership, development and marketing in a low-risk environment. So, get your ideas out there and build something cool with the community!