6 Lessons Learned Maintaining a Popular Open-Source Project

Between 2016 and 2018 I maintained an open-source project with +800k downloads/month. I learned six invaluable lessons by doing this, and I will now share them with you.

How It All Started 🛫

I joined Spotify in 2016 and my team needed a React date picker component. I searched GitHub and found many but eventually decided on one. I integrated it into our website and read the code and documentation. And I quickly realized there was room for improvement in this project. So I made a few PRs to add a code linter, some refactoring, and documentation improvements.

The owner of the project was the one reviewing and approving my pull requests (PRs). And here's where I saw my opportunity! I e-mailed him and asked if he needed help maintaining the project, and he happily welcomed me to the team! Wow! It felt like I had just joined a secret club! I had always wanted to maintain a popular open-source project, and it was exciting.

Maintaining an Open-Source Project 🛠

I had never maintained an open-source project before so I didn't know what to expect! The project was popular and there were a bunch of unresolved issues and unmerged PRs. I started by resolving these and moved on to improving the code quality.

Once I got to know the code base I made more significant improvements, changes to the API for example.

Lessons Learned 👩‍🏫

Two years and 154 commits later and I learned a lot! Here are my six most valuable lessons.

People Are Bad at Reading Documentation 🗒

I spent time writing documentation and improving the onboarding experience for the component. Still, I got questions that were answered in the documentation. It kept happening, and I would try to make the documentation more visible, but it didn't help.

The habit of "I can't make it immediately work, so I'm gonna ask!" is a bad one. As a software engineer, you will need to read documentation to learn and move forward. There won't always be someone to answer your question, and then what will you do?

Good Code Is Subjective 😋

I was a junior engineer when I started maintaining this project. I thought I had things figured out, but oh boy was I wrong. I had the fortune of working with more experienced engineers on this project and I learned a lot. I was confident and thought "This is how you write good code". And then someone would make a PR that would completely go against my beliefs, and I had to re-evaluate what good code looks like.

Now as a senior engineer I see that good code is not always objective. Sure, we agree on some good practices. But there will always be someone that disagrees with you, and with good reasons!

Good Git Commit Messages Are Rare 🤔

This is what surprised me the most about maintaining an open-source project. In an open-source world on GitHub using Git we have a limited space to communicate with our future selves. We should use that space wisely and by best effort try to be as clear as we can when writing commit messages.

That's how I feel anyway, but most people don't seem to agree. I would see PRs without any description and a commit message saying "Fix render bug". Not only is this a bad practice, but it also slows down the process of getting your PR merged.

Merging Someone Else’s PR Is a Great Feeling 😍

If you ever contributed to an open-source project you know the feeling of getting your PR merged. It feels great! I'm part of something bigger! And now I can tell you that it also feels great being the one to press the Merge button. It's a win-win-win situation. The PR author, the maintainer, and the people using the project all win.

People Are Awesome! 🤩

People take time out of their lives to contribute to a component used by people they don't know. This is what open-source is about, in my opinion. People coming together for the greater good. If you're not contributing to an open-source project today, give it a try. If you are, keep doing what you do, you are awesome ⭐️.

It’s Fun but Can Get Exhausting 😰

I had fun maintaining the project, but no matter how much time I spent fixing bugs there would always be new ones. The component was more complex than I first thought. At times there seemed like there was a never-ending stream of new issues being created.

It was basically me alone maintaining it, at this point, with support from a couple of other people. I felt a responsibility because there were real people having real issues. And I could help by fixing the bugs. And so I did. A lot. But it never stopped, and that's when I got exhausted.

Why I Stopped ✋

After two years of working on the project, I realized one day it had gone a month without me touching the project. This is when I decided to stop. I e-mailed the owner and explained. He said it was cool and thanked me for the help. He even sent me some Stuff We All Get (SWAG) from his company! A t-shirt and some stickers. Thanks, Javier!

Conclusion

Maintaining an open-source project is fun. People are awesome! But it can be exhausting.

Here's a summary of the lessons I learned:

• People Are Bad at Reading Documentation 🗒
• Good Code Is Subjective 😋
• Good Git Commit Messages Are Rare 🤔
• Merging Someone Else’s PR Is a Great Feeling 😍
• People Are Awesome! 🤩
• It’s Fun but Can Get Exhausting 😰

If you ever get a chance to try it I recommend you do. There are a million projects out there looking for help, be brave and start contributing! You have nothing to lose.

Connect with me on Twitter, LinkedIn, or GitHub

Originally published at prplcode.dev