The monorepo culture

Kadhir Manickam

(5 minutes)

<section data-section-id='cc19ea37-ba56-4458-aeda-b6f3ec27f79d'>At this point, I've read many articles debating between polyrepos and monorepos<a href="https://"https://en.wikipedia.org/wiki/Monorepo"" target=""_blank"">1</a>. I've also worked in both setups, many of which I've helped put together. I've seen what happens when the polyrepo setup gets pushed to the extreme, where every little API and service is in its own repo, inevitably resulting in dependency hell<a href="https://"https://en.wikipedia.org/wiki/Dependency_hell"" target=""_blank"">2</a>. But I've also seen what happens when a monorepo becomes so overburdened that the average developer struggles to get the tools to work. All day-to-day development slows down a ton. The tooling to make a monorepo work once you've got even a dozen developers in there is no joke. Lots of great discussions on the technical trade-offs between these two setups<a href="https://"https://github.com/joelparkerhenderson/monorepo-vs-polyrepo"" target=""_blank"">3</a>,<a href="mailto:"https://medium.com/@cfryerdev/monorepo-vs-polyrepo-the-great-debate-7b71068e005c"" target=""_blank"">4</a>,<a href="https://"https://graphite.dev/guides/monorepo-vs-polyrepo-pros-cons-tools"" target=""_blank"">5</a>,<a href="https://"https://earthly.dev/blog/monorepo-vs-polyrepo/"" target=""_blank"">6</a>. Honestly though, in my experience, the decision between a polyrepo and a monorepo isn't technical; it's cultural. Inevitably, both lead down sort of miserable paths, but I think that's because getting a lot of engineers to collaborate is hard. No getting around that. Instead, I've been thinking about the cultural implications of each setup and have come to love a monorepo culture. Specifically, one where:<ul><li value="1">Development tools are standardized</li><li value="2">There is one release cycle for the entire repo</li><li value="3">Everyone is responsible for keeping main working</li></ul> So much incredible good happens when those three things are true. And for me, it's all about that feeling of being together, which I've always felt on high-functioning teams. That feeling of our team working together toward shared goals. Let's dive into some specific aspects of good that I particularly love. <h3>Engineers can move between projects with less downtime</h3>The standardized toolkits allow engineers to move between projects without learning a new set of development practices. This results in fewer blockers for management and ICs to cross-pollinate between projects. When team members can contribute to many initiatives, it's a massive win in my books. I think it feels more like the team is doing something valuable than a specific individual within the team, even if that's true in practice. In other words, I think the best teams are those where it's tough to identify the source of a good idea. Rather, the idea came about from many interactions and conversations. When engineers can easily contribute to many projects, I think they're more likely to develop interaction patterns that foster natural collaboration. <h3>Everyone is invested in the development experience</h3>I have often found the work to improve everyone's dev-x experience underappreciated, but in a setup where everyone shares the experience, it's much easier to understand its impact. May not fix the appreciation problem, but hey, at least people can understand better. In many ways, this aspect feels like having a shared meal. While eating together is excellent, eating the same foods together is even better. That's an authentic shared experience! <h3>It's nice to see all the changes in one place</h3>Seeing all the commits roll in and the systems continually update can be energizing, especially if those changes are reflected in your day-to-day local development experience. You can see how everyone's work is coming together and how it's (ideally) getting better daily, without having to go out of your way. But more than that, I can point to a concrete, singular code artifact and say I'm a part of that. That's my team, both past and present, represented in code. That's a community I belong to. <h3>Breaking changes are the responsibility of the author to land safely</h3>This is the most significant cultural impact for me. In a polyrepo world, I can accidentally introduce a breaking change and publish a minor version bump without realizing it. Then it's on consumers to address the breaking changes when they upgrade. As the consumer, that's such a frustrating experience. Now I'm mad at the author for putting me in this situation! Not good for team camaraderie. In the monorepo world, it is my responsibility as the writer to ensure that my breaking change lands safely and does not break main. I have a vested interest in either doing the migration myself or getting help from everyone to land my change. Specifically, the onus of completing the migration of the breaking change has moved from the consumer to the author. Let's go on a tangent for a second and discuss breaking changes that explicitly require consumers to update their code somehow. Migrating code sucks, especially when you didn't write the breaking change, and even more so when you do not understand why the breaks were necessary. I cannot tell you how many times I have dreaded a major version upgrade to React, ESLint, Prisma, Postgres, etc. The old thing worked great, so do I have to change it? Well, those changes are necessary for continued improvement. Someone is working to map out a vision for where these things need to go, and they've determined this breaking change is needed. They've done the emotional labor<a href="https://"https://greatergood.berkeley.edu/article/item/what_is_emotional_labor_and_why_does_it_matter"" target=""_blank"">7</a> of figuring out what needs to happen so we can all benefit. You know what would be even better? If the authors of those breaking changes went around and upgraded everyone! That way, when they come to upgrade my package, I can ask them questions. Now let's tie this back into our monorepo culture. When an author creates a breaking change, they can go around upgrading all the consumers. When they come to upgrade my package, as a consumer, I can understand why the change is necessary and know the direction they're heading. I can make sure my continued usage aligns with where they're heading. And just as importantly, the author can know how I'm using their package so they can continue to stay aligned to what I need. They're forced to stay close to their customers. That's a fantastic team interaction right there! It results in better long-term alignment between authors and consumers. Way less frustrating than having something perceived as semi-random, tossed over a fence. I love this! This is an interaction that we can force in a monorepo world. This is all to say that when debating polyrepos vs. monorepos, I have often found much healthier engineering cultures in the monorepo world that better foster a sense of teamwork.</section>