DEV Community

Cover image for 6 Lessons Learned Maintaining a Popular Open-Source Project
Simon Egersand 🎈
Simon Egersand 🎈

Posted on • Originally published at prplcode.dev

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

Discussion (22)

Collapse
rajasegar profile image
Rajasegar Chandran

We can make good commit messages common by adding the necessary tooling for the repositories like Conventional commits and enforcing the style with linters and git hooks. It will also be easy for the contributors to follow a standard convention if there is one already available for them to refer.
Anyway as a fellow maintainer, I can agree with you on these lessons.

Collapse
simeg profile image
Simon Egersand 🎈 Author

In my experience, tooling can only do so much to help with good commit messages. I believe more in a good mindset. If you know the value of a good commit message you will write a good commit message. But if you don't know the value it might just be an inconvenience.

Collapse
user64bit profile image
ARTH PRAJAPATI

Wow, that was great πŸ‘
I was thinking about maintaining open-source project,

Thanks for sharing your experience

Collapse
simeg profile image
Simon Egersand 🎈 Author

I'm happy you liked it! :)

Collapse
areful profile image
Areful Islam🀝🌎

Keypoints are great. Is that all open-sources are same scenario?

Collapse
simeg profile image
Simon Egersand 🎈 Author

This is my experience. I don't know how it is for other projects. But I would guess many maintainers can relate.

Collapse
stvbyr profile image
Steve Beyer

Nice read! Regarding the documentation part I’m quiet on the opposite. I am happy to read documentation because than I don’t have to ask questions. πŸ˜„

Collapse
simeg profile image
Simon Egersand 🎈 Author

OSS maintainers love people like you πŸ˜„

Collapse
shinigami92 profile image
Shinigami

Happy to read your experience
I'm one of the maintainers of FakerJS and I can definitely agree with most of your experiences

Collapse
simeg profile image
Simon Egersand 🎈 Author

That's, in a way, comforting. I'm not alone πŸ˜‹

Collapse
aquadrehz profile image
AquaDrehz

I saw python lib named diagrams.
It used to create diagram picture from code. It got a hundreads of PR remained. Still thinking to hop on. But python is not my prefered language. Any suggestion?

Collapse
simeg profile image
Simon Egersand 🎈 Author

My advice is to try it! You will learn something, even if Python is not your preferred language. Consider it a challenge and I think you'll enjoy it :)

Collapse
lorenzojkrl profile image
Lorenzo Zarantonello

Nice one!
Good food for thought!
I think everyone could be a bit more aware of that little Git Commit we write multiple times per day!

Collapse
gulshanaggarwal profile image
Gulshan Aggarwal

Amazing content!

Collapse
simeg profile image
Simon Egersand 🎈 Author

Thanks, Gulshan! I'm glad you liked it :)

Collapse
andrewbaisden profile image
Andrew Baisden

Super insightful not everybody has a first hand experience working on open source projects. Great article.

Collapse
simeg profile image
Simon Egersand 🎈 Author

Thanks, Andrew! I learned a lot and I would recommend this to anyone who's up for a challenge :)

Collapse
drwrongmo profile image
Jon Wright

I'd love to see a follow up post of what you think a good commit message entails.

The must haves. Things to consider including. Things to exclude.

Collapse
simeg profile image
Simon Egersand 🎈 Author

I love discussing what makes a good git commit message. That's a great idea! I've added it to my list of topics.

Collapse
glenn_miller_860ba12ffbf7 profile image
Glenn A Miller

"Stuff We All Get"

Thanks for that!

I always wondered what that stood for.

Collapse
laianbraum profile image
Laian Braum

Such a short and great read! Thanks for this article, Simon! You gave me some really interesting points to think about.

Collapse
simeg profile image
Simon Egersand 🎈 Author

Thanks! I'm glad you liked it.