The art of maintaining an open source project

While anyone can throw a lab assignment up on GitHub for all to see, building a large project with user support, documentation, and effective contributor coordination is a different story. Developers frequently enter open source without recognizing how to measure and improve project health, later finding out the massive importance of keeping their product well maintained when other developers come to depend on their work.

Moov started with several open source libraries that continue to be heavily relied on by major players in financial services. Over the years, we’ve developed some best practices for keeping these projects healthy. In this guide, we’ll share our strategies, as well as how you can contribute to our wide range of open source libraries. We hope you can take some of these principles and apply them to your efforts.

Identifying roles

It’s essential to define the main parties involved in open source software: maintainer, contributor, and user. Being a maintainer doesn’t just mean writing code. It entails a wide range of responsibilities, including:

• Code reviews
• Handling support inquiries
• Timely responses to open issues, pull requests, and feature suggestions
• Participating in and potentially hosting community events
• Acting as a gatekeeper to breaking changes and investment of resources (such as refactoring)
• Ensuring backward compatibility
• Being a public face of their project
• Having in-depth knowledge of the industry their project lives in

As you can see, becoming a maintainer is no joke! While we’re always looking for new maintainers for our open source projects, there’s quite a bit to take on. On the other hand, being a regular contributor may be less intimidating. Contributors are responsible for:

• Writing code
• Working with a maintainer to establish and communicate the vision
• Keeping a steady cadence on contributions
• Assisting other contributors

While it’s nice to believe that contributors will be a bunch of different people, the reality is that a few dedicated contributors write 90% of the code on a given project. Still, casual contributors lessen the burden on maintainers, allowing them to focus on areas besides writing code.

Unlike a contributor, a maintainer is responsible for weighing the long-term impacts of changes to a codebase. For example, a maintainer might reject a change that provides an immediate benefit but will require a ton of maintenance work down the road. The role also includes keeping scope dialed since a seemingly useful feature may fail to fit within a project’s purpose.

Lastly, a user is pretty self-explanatory—they use a codebase but don’t contribute directly to it. A user may fork a repo and make changes but never submit a pull request to merge those modifications. However, users may still be involved in community activities. Here at Moov, we have a great group of users who continuously pitch in, even if they aren’t directly making GitHub changes.

Ultimately, maintainers, contributors, and users each have roles to play for a project to be successful. As a maintainer, there’s nothing more useful than community engagement. Whether that’s reporting a bug, building a feature, answering user questions, or only making it known you exist, maintainers love helpful interaction.

Determining project type

Open source software comes in all shapes and sizes. As a result, it’s impossible to establish a single set of maintenance/contribution rules that’s effective across the board. A better approach is to classify projects and then work on a maintenance plan based on the categorization. In Working in Public: The Making and Maintenance of Open Source Software, Nadia Eghbal introduces a reliable approach for identifying project types. She suggests four groupings can exist based on user growth and contributor growth.

If we commit to this strategy, it’s much easier to determine a project’s needs. Toys are so small in scope that they’re usually best off with one or two maintainers and the occasional traveling contributor. On the opposite side, federations aren’t too common. The few federations out there have typically adopted similar structures to companies, dividing their contributors into teams, holding scheduled meetings, and collaborating closely with corporations/sponsors. Clubs have very passionate user bases, where most users become contributors.

With all that said, we’ll be referring to stadiums for the majority of this article, as they’re the most common type and arguably the most confusing to maintain. Several of our open source libraries started as toys and quickly morphed into stadiums.

Stadiums involve a small number of maintainers who must manage occasional contributions from a massive group of users. The main challenge here is figuring out the needs of those users and responding accordingly. A stadium’s audience can be deceptive, as it may seem as though few developers are even aware of the project, even though it’s actively being used by many. Therefore, it’s essential to keep plans and documentation public where possible so users know what to expect.

Assessing project health

Now that we’ve identified project roles and types, we can measure health. Measuring health looks a little different depending on the project type. Toys usually don’t require much work, so they are healthy as long as they are stable. For the other types, one useful metric is the bus factor. The bus factor is the number of contributors who need to be hit by a bus before the project stalls. Morbid? Yes. But you quickly get the point. Improving bus factor is much easier said than done, but doing so gives your project extra lives.

It should be noted contributor count alone isn’t a reliable way to define health since many contributions may be one-off changes or fail to make a significant impact overall. Other metrics to consider when examining project health are:

• Number of open issues and pull requests
• Response time
• Overall activity (commits, issues, pull requests, comments)
• Time to close an issue or pull request
• Number of stars and forks
• How much the project is dependent upon

We pride ourselves on having a great response time to new issues, pull requests, and questions. We find this helps contributors stick around to completion for pull requests and lets you know we genuinely care about our open source offering’s quality.

The road to success

There are tons of strategies that maintainers can employ to improve the overall health of their projects. These work to enhance the previously listed metrics for measuring project success and reduce “busy work” for maintainers. Increasing bus factor by recruiting maintainers and dedicated contributors is a major one, but some additional suggestions include:

• Incorporating forms of automation to reduce the need for maintenance
• Publishing a development roadmap and contribution guide
• Clearly defining project scope
• Setting templates for issues and pull requests
• Being friendly and open to new ideas
• Creating community events and a place for collaboration like Slack, Discord, or Gitter
• Writing extensive documentation
• Establishing fine-grained, modular tasks

Maintainers should recognize that user and industry needs are always changing. Do not take a development roadmap as set in stone. To be successful, it helps to reevaluate decisions continually. This mentality allows a project to be as dynamic as its environment makes it easier to improve its health.

Example contributor interactions

We had a significant interaction recently, where a user became a contributor after interacting with a maintainer. This example is the ideal scenario in open source and a sign of a successful project.

Vincent Lucero is a project manager for Clowte, a startup that reports student payments like rent to credit bureaus, helping students build credit histories. He initially joined the Moov community because he was having an issue using Docker. Now that he and his team are beginning work on integrating Metro2, he ran into an issue with the API service:

Vincent had some great feedback on making these errors more straightforward upon further interaction—adding a verbose flag for getting detailed error messages. Instead of trying to replicate his problem, Graham (our Community Manager) asked if he’d be willing to make an issue, and he did.

As a maintainer, you can’t ask for better feedback or engagement from your community. By responding quickly, you’re more likely to get input like this. Enabling your project to support these types of interactions is recommended.

Conclusion

Keeping an open source project active and well received can be tricky. Maintainers have a lot on their hands, but contributors and users can make their lives easier (or harder). Encouraging a collaborative community for your projects goes a long way in reducing the load of work put on maintainers. But remember, there have to be specific systems in place to utilize interactions best.

We are continually working to grow our projects and incorporate user feedback. If you’d like to help, we encourage you to join our Slack channel and take a look at our OSS projects. (And if you’re interested in becoming a maintainer, please let us know on Slack!)

Further reading

• Best Practices for Maintainers - Open Source Guides
• How to Maintain Open Source Projects - Digital Ocean
• How to be a Good Maintainer - VMware
• Working in Public: The Making and Maintenance of Open Source Software - Nadia Eghbal