A collection of characters, stories, and other elements
We’re experimenting with a new way to think about code ownership, and have built a new tool called Codenotify. Codenotify enables developers to easily subscribe to file changes in a Git repository without creating the expectation that changes to those files are blocked on the subscriber’s review.
We host all of our code on GitHub, so up until now we have been using a GitHub CODEOWNERS file in each repository. When someone opens a pull request, GitHub will look at the CODEOWNERS file to determine which reviewers to automatically add.
As our team has grown over the past year, I started to observe patterns that made me think that the way we assigned code reviewers was flawed.
My diagnosis was that there were two problems:
I had a hypothesis—that we needed something other than CODEOWNERS—but it needed validation. Was the team feeling the same pains and observing the same patterns as I was? Was continuing to use CODEOWNERS a viable solution moving forward?
To get the sentiment of the team, I opened a pull request that proposed deleting CODEOWNERS with my reasons and asked the entire team to submit anonymous feedback. Here were the results:
In the free-form comments, responders provided extra context about their support, concerns, and suggestions for the proposal. Here are a few representative examples:
It was clear we needed something, but CODEOWNERS didn’t do exactly what we needed and we didn’t have the ability to change its behavior.
There was enough evidence that a problem existed to justify exploring alternatives.
I found Fullstory’s blog post about how they ran into similar problems with CODEOWNERS and ended up creating a bot. I would have loved to experiment with using their bot, but unfortunately it was not open source.
A few of our teammates, including myself, worked at Google so we were familiar with the OWNERS format used internally and in the Chromium project. This would have been an improvement over CODEOWNERS because multiple files are easier to maintain than a single large file and Chromium’s implementation explicitly attempts to minimize the number of reviewers, but I was worried this would continue to create a gatekeeper culture around modifying code.
I wanted a solution that would:
Neither CODEOWNERS nor OWNERs were designed with all these requirements in mind, so I started to think about what a new tool might look like, and I ended up with Codenotify.
As the name implies, Codenotify is designed around the concept of notifications, not about establishing “ownership” of code or mandating “reviewers”. Codenotify works on the command line and is codehost agnostic at its core, but it is also packaged as a GitHub Action so it is easy for repositories on GitHub, like ours, to adopt. The GitHub Action sends notifications to subscribers by mentioning them in a comment instead of adding them to the official “reviewers” or “assignees” lists on GitHub.
Notification rules are stored in CODENOTIFY files in any directory. This makes rules more maintainable and less brittle to moving code because the CODENOTIFY files are adjacent to the files they have rules for.
Codenotify rules and files are familiar in syntax to CODEOWNERS, but simpler to understand because each rule is additive, not hierarchical. This means that you can understand how a single rule behaves without needing to consider any other rules (unlike OWNERS or CODEOWNERS).
If you want to learn more about Codenotify or try it out for yourself, then the project's README has everything you need to know!
After I had a working prototype of Codenotify, it was time to actually experiment. Experimentation is a great way to discover unforeseen costs and benefits, and learn whether hypothetical problems are problems in practice.
We deleted our CODEOWNERS file on September 16, 2020, and teammates have been adding CODENOTIFY files ever since.
At the end of October I will check in with the team to see how they are feeling about this experiment after having lived with the change for over a month. The exciting thing is that no matter what the outcome is, we will have learned something new.