Six Valuable Insights from Managing a Popular Open-Source Project
Written on
Chapter 1: The Journey Begins
My adventure into open-source began in 2016 when I joined Spotify. My team required a React date picker component, so I scoured GitHub and found several options, ultimately selecting one to integrate into our platform. Upon reviewing the code and documentation, I recognized potential for enhancements. I submitted a few pull requests (PRs) to introduce a code linter, refactor some sections, and improve the documentation.
The original project owner reviewed and approved my contributions, which led me to reach out via email, offering to assist with project maintenance. To my delight, he welcomed me aboard! It felt exhilarating, as if I had been granted access to an exclusive club. My aspiration to maintain a prominent open-source project was finally coming true.
Maintaining an Open-Source Project
Having never taken on such a role before, I was unsure of what to expect. The project had gained significant traction, resulting in numerous unresolved issues and unmerged PRs. My initial focus was on addressing these concerns, followed by efforts to enhance code quality. As I became familiar with the codebase, I made more substantial changes, including adjustments to the API.
Lessons Gained from Experience
After two years and 154 commits, I gathered several valuable insights. Below are the six lessons that stood out to me.
1. Documentation is Often Overlooked
Despite my efforts to create comprehensive documentation and streamline the onboarding process, I frequently received questions that were already addressed in the guides. This pattern persisted, and my attempts to make the documentation more accessible failed to yield results. The mindset of "I can't get it to work, so I'll just ask!" can be detrimental. As a software engineer, it is crucial to learn to navigate documentation independently.
2. The Subjectivity of Good Code
When I began, I was a junior engineer, convinced I understood the essence of quality coding. However, through collaboration with more seasoned engineers, my perceptions shifted. Confident in my approach, I was often challenged by PRs that contradicted my beliefs about good code. Now, as a senior engineer, I recognize that while certain best practices are widely accepted, differing opinions will always exist—often with valid reasoning.
3. Clear Git Commit Messages Are Rare
This aspect surprised me most about managing an open-source project. In the GitHub ecosystem, we have limited space to communicate with future selves through commit messages. It's essential to utilize that space thoughtfully and strive for clarity. Unfortunately, many PRs lacked adequate descriptions, often featuring vague commit messages like "Fix render bug." This not only reflects poor practice but also hinders the merging process.
4. The Joy of Merging PRs
If you've ever contributed to an open-source project, you know the thrill of seeing your PR merged. It’s a fantastic feeling of belonging to something greater. As a maintainer, pressing the Merge button brings just as much joy—it’s a mutually beneficial scenario for the PR author, the maintainer, and the end-users.
5. The Power of Community
One of the most heartwarming aspects of open-source is witnessing individuals take time out of their lives to contribute to projects that benefit others. This communal spirit embodies the essence of open-source: collective effort for the greater good. If you haven't yet engaged with an open-source project, I encourage you to try it. And if you are contributing, keep up the great work!
6. The Balance of Fun and Exhaustion
While I genuinely enjoyed maintaining the project, the relentless influx of new bugs and issues became overwhelming. The complexity of the component was greater than I initially anticipated, and despite my efforts to address bugs, they continued to arise. With only a small amount of support from others, I felt a strong sense of responsibility to resolve these issues. Eventually, the never-ending nature of the work led to my exhaustion.
Deciding to Step Back
After two years, I realized I hadn’t engaged with the project for a month. This prompted me to reach out to the project owner to inform him of my decision to step back. He was understanding and expressed gratitude for my contributions, even sending me some company swag—a t-shirt and stickers. Thank you, Javier!
Conclusion
Managing an open-source project can be incredibly rewarding, filled with inspirational people. However, it can also be draining. Here’s a quick recap of my insights:
- Documentation is Often Overlooked
- The Subjectivity of Good Code
- Clear Git Commit Messages Are Rare
- The Joy of Merging PRs
- The Power of Community
- The Balance of Fun and Exhaustion
If you ever have the chance to get involved, I highly recommend it. Numerous projects are seeking assistance, so be bold and start contributing! You have everything to gain.
Connect with me on Twitter, LinkedIn, or GitHub.
This video, titled "An Amazing Open-Source Project to Learn From!", discusses outstanding open-source projects that can serve as great learning resources.
The video "5 Open-Source Projects to Learn From" highlights five notable projects that offer valuable insights for contributors.