9 things I wish I knew when starting open source project

For more visibility posting this on medium. The original article is posted on my website. :)

This blog is about things I wish I knew or someone would have told me before starting an open-source project.

There are many types of open-source projects. We are not going to talk about big projects like Flutter, Kotlin, Android and React. Those projects are managed by giants companies that have large teams and investments.

We are going to talk about those open source projects which are created or managed by an individual developer on weekends with a full-time job. (Basically, people like me 🤪)

So let’s get started…

1. Writing tests

It’s sad that in the software industry writing test is still not a norm. In some projects, writing tests is considered a separate task instead of being part of the development cycle. I am not advocating TDD or 100% coverage here, although they have their pros and cons.

My point is to start regularly writing tests for basic business logic or end-to-end tests, which will create a habit of writing tests whenever you add something new.

3 years back I open source my android library without any test which leads to a lot of manual testing before I publish the library.

I started writing unit tests with 30–40% test coverage. In beginning, it was hard and took most of my time.

The value of this test shined when other people started contributing to the project. It saved a lot of time. I highly recommend asking contributors to write tests as well or else you will keep merging code with less coverage. Then I started writing end-to-end UI tests and it increased the code coverage to 60–70%.

Note: Those tests are not perfect and do not cover all edge cases. But it gives me enough confidence to merge and published it.

Tip: If you want to check the health of the project then look at their tests.

2. Automation

Automation saves time for repetitive tasks. We need to define it once and the machine will take care of it.

I learned 3 useful automation tools and techniques from my open source projects.

1. CI/CD

As I mentioned in the “Writing tests” section where I need to do a lot of manual testing before publishing the library. Even after writing tests, there were few repetitive steps that I need perform i.e running tests, running lint check, building jar, and publishing jar.

CI/CD is the solution for all these problems. 2 years back I was not familiar with CI/CD. It took me a month to set up the CI using a free Circleci service with help of DevOps at my workplace.

After using Circleci for a year, I switched to Github Actions for 2 reasons.

1. GitHub Actions usage is free for both public repositories and self-hosted runners.
2. It’s easy to set up if your project is on GitHub.
3. Basic tools are available on Github Action Marketplace

2. Using Bots

CI/CD took care of development and deployment workflow. I use bots for management workflow. Bots can be used to automatically add labels and update the status of an issue.

I learned this bot technique from other open-source projects like Flutter and Kotlin where if the issue has no activity or comment for X number of days then the bot first adds a warning comment, on the issue or PR, and then after Y number of days, it closes the issue.

My personal experience with open source projects is that most developers do not write a descriptive issue and need constant follow-up.

This bot also helps to close spam issues and all those create-and-forget issues.

3. Use Templates

Technically templates are not automation, but it avoids lots of receptive tasks.

As I mentioned above due to a lack of descriptive issues there is a lot of back and forth to get minimum info to reproduce or understand the issue.

This can be avoided by creating a template. Asking for all those information upfront while creating an issue. We can add, Example Device Info, Steps to reproduce the issue, Current Behaviour, and Expected Behaviour, and so on.

3. Perfect is the enemy of good.

One of the key learning for me as a professional was to know when something is “Good Enough”.

In beginning, I was obsessed with Perfection. Everything needs to be perfect i.e variable names, function signature, API design, and using design pattern perfectly.

First of all, getting a PR from someone in an open-source project is a big thing. I rejected more PR because it does not look perfect to me even though it was doing a good enough job.

This might work if you are working solo. But as soon as more people are involved with different experience, culture, and their definitions of perfection then things started to get messy.

I learned two things.

1. You need to make compromises on something to make progress.
2. Open source is more about collaboration and people projects rather than creating something perfect.

4. Avoid delaying the response.

If more developers started using your library, you will start getting a lot of issues, PR, and queries. Response them quickly (NOT urgently). Because delaying response will have a high chance of losing the context on the issue. Or making the developer less interested in the issue.

I underestimated the cost of a delayed response. I learn this hard way when I took 1 year and 3 months to review and merge a PR. I appreciated the contributor’s patience here.

To avoid this, I’ve dedicated time in a day to respond to those queries which I time-boxed to 20–30 minutes which force me to come up with a reply. I ask for clarification if I don’t understand something.

Don’t wait or delay. Review issue and PR quickly. (NOT urgently).

You don’t owe your time to the user. This is your community work and it’s free. My point is that delaying response will lose the context around the issue.

5. Be kind and humble.

Having a lot of issues and feature requests is a good sign that your project getting a lot of usage and attention.

But sometimes people become rude and demanding with comments like.

1. Can you please fix this ASAP?
2. My project is stuck because of this issue.
3. I will use your project if you add this X feature.
4. Or something like “You need some expert”

This section is NOT for the project maintainer but instead for the user. If you face any issue with the open-source project then be kind and humble while filling the issues.

Help the maintainer with PR or a good descriptive issue instead of just putting everything on the maintainer. This will go a long way and will solve your problem as well.

6. It’s hard to find maintainers/contributors.

Working on a project solo is fine. But when things start to grow you will need helping hands. You will need a people with similar goals and mindset. The problem is… Those people are very hard to find.

I was solely working on an open-source project for 3 years. It was getting difficult for me to maintain the project. I reached out to various social media platforms to find maintainers.

I got few replies but nothing concrete. Then someone who has contributed to this project in past, reach out to me to help me with some issues. It is a good head start for me.

The key learning for finding maintainers is to be explicit about it and make it easy for them to contribute.

If you are interested in contributing to this project then reach out to me or you can start the discussion here.

7. Be cautious about making APIs public in libraries.

If you are building an SDK or libraries then be cautious about making any function or class public.

The reason being that once you made it public then there is no easy way back. You need to support that API until you have a depreciation strategy or introduce breaking changes that break the client code (which I won’t recommend).

Languages have different ways of making it public. For example, Java has public keyword for this. Just be aware of this in whatever language you choose.

8. Expect the unexpected.

People will use your project in unexpected ways. It can be good and bad as well.

The Good: I didn’t expect that someone will use this library for editing T-shirts.

The Bad: Blindly copying stuff and claiming it their own.

9. Don’t stress about it.

Working on something you are passionate about will eventually lead to a strong emotional attachment to it.

This leads to burning out and stress if you are actively working on it with a full time job.

There are more things in life beyond this projects which you can also enjoy as much as this, without feeling guilty about it.

What works for me was instead of spending ad hoc time on open source projects now I’ve set fix amount of hours. It would be working weekly or monthly basis based on my availability.

And it’s totally fine If I don’t find any time for it.

This gives me more control over time and feel less guilty or stress if I am not doing it.

So that’s it. Those are my 9 learning so far in the open-source project. I would love to know other people learning as well. So let me know in the comments.

Thank you for taking your time to read this article.

In case you have any question, you can reach me on Twitter or Email me.

If you like this kind of content then you can subscribe to my blog and be the first one to get notified when any new content is published.

If you like this article, please like and share it with your friends/colleagues and help me to spread the word.