What are maintainers doing to ensure OSS projects are safe and effective?
As an open source maintainer and long-time contributor, I can happily say that getting stuck into open source software (OSS) can change the way you work. For the better.
When I first started my own OSS journey, I was surprised to discover that open source was the way software began in the 80s at MIT. In fact, proprietary software is the new kid on the block. Back then, innovators knew that in order to create something brilliant, you needed to keep the codebase open for contributors. That you’d naturally want more brains working on something rather than restricting it to just a few. Software would be shared, built in the open, and shared again.
Forgive me then, because when I first heard the words ‘open source’ I was well into my thirties and the idea that ‘volunteers’ would be contributing to a project sent chills down my spine. How could we be sure everyone knew what they were doing? What if someone made a malicious contribution? How much faith could a client, or end user, have in a piece of software that was being built by people whose jobs didn’t depend on their work being good?
Thankfully, gone are the days when people would see the words ‘open source’ and run away to work with a different platform. But how did we get here and what do we do to ensure OSS is both safe and effective for those who depend upon the product and those who maintain it?
In this article, we’ll look at a handful of ways that open source maintainers work to ensure the safety of the software, based on my own experience as a maintainer for Umbraco-CMS. We’ll look at the importance of test coverage, how to handle merging processes, the human touch vs. bots, and how with good communication we can ensure the friendliness of the entire ecosystem.
Open source maintainers aren’t saboteurs
Something I’ve learned during my time as an open source maintainer is that very few developers sit at their desks, peruse open source projects, and think to themselves, ‘whose software will I destroy today?’
I’ve reviewed countless pull requests on Github in my current role, and I’ve spent many years before that working in a voluntary capacity to do the same. I can honestly tell you the only pull requests I’ve encountered that have been cynically raised have contained, at worst, a pointless change. With 3891 pull requests submitted to the Umbraco CMS codebase over the last 5 years, we’re certainly not giants, but a ratio of 0 rejections out of almost 4000 submissions speaks for itself.
The importance of test coverage
Like any OSS with a thriving contributor base, though, we have tests in place to ensure that some big questions have been answered before any human gets a chance to review the submitted code:
- Does this contain anything obviously malicious?
- Will this inadvertently break everything?
- Are there any other red flags in here?
Test coverage is incredibly important. I’m not the kind of dev that will tell you that there’s a minimum percentage you need to be working with here. I don’t believe there is a magic number that inspires confidence. That said, test coverage that addresses the major security issues doesn’t just give your OSS a better chance of surviving while it grows, it also gives your contributor confidence in what they are doing.
I know this first hand. For my first pull request, I cobbled together the change I wanted to make and when I was done, I ran it past another dev. I asked her, ‘Is this okay?’ She told me that of course it was, if it worked. But my concern was greater than that. Was I going to somehow break everything if I hit that green button on the Github UI? I knew that was unlikely (I’d removed some formatting from some text) but despite this logic, I was afraid. My friend showed me the acceptance tests and I was instantly reassured. Tests can be time-consuming and figuring out what data to test and what to test for is rarely straightforward (we could talk about that all day). But having the right tests is essential in OSS. It doesn’t just reassure you, the maintainers, it also reassures your contributors.
Handling merging processes
It isn’t just test coverage that keeps your software safe. Merge processes that are transparent and rigorous are also key. Back in 2017, I was fortunate enough to join a team of community maintainers for Umbraco-CMS. At this time, the project had eight major versions and an active contributor community in the thousands. I would be one of five community members responsible for reviewing pull requests as they came in. The number of unmerged, unreviewed pull requests on the repository didn’t reflect the commitment and gratitude of those internal developers maintaining the project. There just wasn’t a plan in place for dealing with the increasing community contributions.
As a team, myself and the other community members set about our tasks, deciding which pull requests we loved, which needed work, and which wouldn’t make it into the codebase. We worked hard at creating a framework by which we would assess things. Did we like the change? If so, did we like the approach? If so, did we like the code? Our enthusiasm couldn’t be faulted but after six months of hitting approve/request changes, we realized there was a bottleneck that we could do nothing about. Without merge rights, we were always going to have the same problems. Good work just wouldn’t get merged in a timely fashion.
It was then that the ‘contrib’ branch was born. While it felt outlandish for even the friendliest of projects to give community members, working on a voluntary basis, merge rights to a repository, it seemed the most sensible way to proceed. GitFlow is a wonderful thing. Creating a branch that ran parallel to the ‘dev’ branch and was regularly merged into it meant that community members could safely merge pull requests after carefully reviewing the content.
Good communication is everything
Once again, this gave our contributors reassurance. We now had checks and balances in place to ensure that contributions were safe, sound, and wanted. Naturally, we didn’t keep this process secret. We regularly blogged about these processes. Each time we reviewed them, we told our community. When we communicated on the repository, we’d link our posts. We knew that what makes a contributor happy isn’t just a notification that their code has been merged or the pull request has been closed but also being made a part of that process.
As maintainers, we should tell our community why we like what they’ve built. We should tell them where they could go next. The more we tell them, the likelier it is that they’ll set about building something we’ll all love. It’s better to talk now than down the line when we’re explaining why the contribution they’ve submitted won’t be merged.
The human touch vs. bots
You might ask, ‘who has time for all this?’ And you’d be right to. We don’t. That’s why we created the Friendly Umbraco Robot to handle the comms that our contributors need to read but don’t necessarily need the human touch.
So much of what we want to tell contributors, we aren’t telling them for the first time. Many devs coming to our project will be contributing to many codebases and won’t know what to expect after they submit a contribution. We have documentation and that’s a great base, but we’ve found it’s much easier to send an automated message than expect folks to look things up themselves.
We knew what we didn’t want to automate – and that list was long. When people take the time to contribute to your project, whether it’s raising an issue, fixing a bug, or spending hours building a feature, it’s important to acknowledge their work personally wherever possible. We worked backward from that and our robot was born.
I like to think of our bot as particularly friendly. It has a handful of different phrasings of similar messages. Our project is a CMS so we had fun creating semi-human sounding messages to speak to our contributors. The friendliness really comes from the bot’s function. Our bot pops a message in response to a pull request and lets the person know what will happen to their contribution: how it’ll be reviewed, the timescales, and what things we’ll be taking into consideration when we do our review. This way, experienced contributors can enjoy the acknowledgment of their submission, and brand new or returning contributors can learn more about where their work fits in. The joys of this being a CMS and Hangfire-powered bot are such that we can update this info each time the process is adapted.
Reflections
As developers, we learn to build because we want to improve things. We all know how frustrating it is when we’re using a tool and it gets in our way. With OSS, maintainers have a way to change that. And so we do. When we talk about safety and effectiveness, it’s very easy to forget that a healthy ecosystem involves a careful balance between process, tech, and the people who are maintaining it. When we lead with friendliness in all we do, we’re able to ensure the effective and safe use of our open source projects.
