Many companies start with a monorepo and then move to a polyrepo setup as they grow. However, as these companies become larger and more complex, many of them transition back to a monorepo to standardize their internal processes and improve collaboration and code quality. As companies grow and evolve, so do their code management practices.

This is a story of this evolution.

Episode 1: Monorepo – The Force Awakens

A long time ago, in a galaxy far, far away…

A small Rebel Alliance started a company. As they were a small team, they began with a monorepo, which made the collaboration and knowledge sharing easier. The master Jedi Martin Fowler had shared that starting with monolith architecture is the right approach for most companies. A monolith architecture would also allow them to continue collaborating into a monorepo.

Episode 2: Polyrepos – Attack of the Clones

As the empire grew in power and the codebase expanded, the monorepo became too large and unwieldy, making it difficult to work with and slowing down development.

The primary reason for slow development? Growing build times. Running the entire build on every change caused build times to become the bottleneck. Furthermore, as the complexity grew, these builds became unstable, leading developers to encounter flaky tests. And the darkness grew.

Also, as the Rebel Alliance tried to maintain control, concerns about code ownership grew. With all code stored in a single repository, managing who had access to which parts of the codebase became harder, and ensuring code changes were properly reviewed and approved by the correct code owners became a challenge.

Eventually, the clone wars began, emboldening the Stormtroopers to continue cloning and creating new repositories across the galaxy.

Episode 3: A New Hope

With the First Order, developers became completely disconnected and had no understanding of what was happening in other parts of the galaxy. Coordinating their efforts and keeping track of changes proved challenging.

From a galaxy far, far away, a new Resistance was born. They knew that if they could harness the power of the monorepo, they could achieve greater efficiency and collaboration.

The Separatists rejected the concept of a monorepo, as they had seen scaling issues with it in the past. This allowed them to operate more independently but made it difficult to coordinate their efforts, leading to inconsistencies in their codebase.

However, the Resistance knew that, despite the challenges of working with monorepos, the benefits of a monorepo setup outweighed the drawbacks. They also understood that winning the war would not be easy, as managing monorepos at scale comes with a significant overhead.

Episode 4: Return of the Jedi

Transitioning from a polyrepo setup to a monorepo at scale was a complex and challenging process. A Jedi task force was assembled to handle this mission. The Jedis came from some of the largest galaxies, like Google and Facebook, which had seen monorepos work at scale.

To transition successfully, they:

• Carefully planned the process and created a migration plan that outlined the steps involved.
• Ensured that all teams were on board with the change and understood the benefits of a monorepo setup.
• Identified the most critical parts of the codebase and migrated them first.
• Addressed concerns about code ownership and access control by implementing appropriate access control mechanisms and policies.
• Used automated tools to help with the migration process, such as those for dependency management, code reviews, and testing.
• Tested the new monorepo setup thoroughly before rolling it out to the entire organization.
• Provided training and support to developers to help them adjust to the new workflow and processes.
• Monitored the performance of the new monorepo setup and made adjustments as needed.

Episode 5: A New Order

By using modern tools, the small team of Jedi was able to bring the developers back to the light side of the Force. They learnt that it’s not that monorepos don’t work at scale, it’s rather the lack of tooling that makes this hard.

Here are a few things that, if done well, can bring the benefits of polyrepos in a monorepo setup while providing the standardization and collaboration benefits that monorepos offer:

• Code ownership: Define granular code ownership and use the CODEOWNERS file properly to provide enough independence to each team while managing consistency across the organization.
• Dynamic builds: At scale, you cannot afford to run full builds on every commit. Define build rules that help run a subset of changes. Most CI systems these days offer opportunities to create dynamic pipelines. You can also leverage Bazel-like build systems to cache partial builds.

May the Force Be With You!

With modern CI systems, smart build strategies, and clear code ownership, they created harmony between independence and unity. In the end, the Force wasn’t in choosing between monorepos or polyrepos—it was in knowing how to wield them.

May the 4th Be With You!