From a Single Repo, to Multi-Repos, to Monorepo, to Multi-Monorepo

This project's evolution mirrors many software development journeys: starting simple, then adapting to growing complexity. Initially a large, monolithic application within a single repository, it evolved through multiple stages of architectural refactoring and repository management.

Stage 1: The Single Repository Simplicity

The leoloso/PoP project began as a WordPress site, combining theme and plugins in a single repository. This offered initial ease of development, but quickly became unwieldy as more sites with similar features were added. The repo grew to encompass roughly ten sites, creating a maintenance nightmare. Searching and replacing strings across multiple sites proved incredibly inefficient.

Stage 2: The Multi-Repository Challenge

To address the scalability issues, the application was refactored into independent PHP packages managed by Composer. This necessitated a shift to a multi-repository structure, one repository per package. While promoting code reusability and better architecture, managing over 200 repositories became extremely burdensome. Versioning dependencies and coordinating pull requests across numerous repositories proved incredibly complex. The lack of a centralized management system hindered efficient development.

Stage 3: The Monorepo Efficiency

The solution was a monorepo—a single repository hosting all packages. This streamlined version control, allowing for simultaneous releases and simplified pull requests. However, since Packagist requires individual repositories for package publishing, a two-pronged approach was adopted: the monorepo for development and separate repositories for distribution. This required a process to "split" the monorepo, handled using the Monorepo Builder tool. This stage significantly improved development speed, particularly during refactoring. The ability to release multiple WordPress plugins simultaneously via customized GitHub Actions workflows further enhanced efficiency.

Despite its advantages, the monorepo presented limitations: enforcing a single license across all packages, managing a large issue board, and the independent versioning of packages even without code changes.

Stage 4: The Multi-Monorepo Solution

The need to manage both public and private code led to the adoption of a multi-monorepo architecture. A public monorepo (leoloso/PoP) serves as the upstream repository, while a private monorepo (leoloso/GraphQLAPI-PRO) acts as a downstream repository, incorporating the public monorepo as a Git submodule. This allows the private repository to access and extend the public codebase, enabling the generation of both public and private plugin versions using a single, adapted workflow.

However, this approach introduces complexities. The downstream repository needs to explicitly checkout submodules, requiring careful management of workflows and potentially breaking changes in the upstream repository. This necessitates careful code review and communication to prevent unintended consequences.

Conclusion: An Ongoing Journey

The evolution of this project's repository structure highlights the importance of adapting to changing needs. Each stage offered advantages and disadvantages, ultimately leading to a multi-monorepo setup that currently meets the project's requirements. However, future needs may necessitate further iterations in the repository management strategy. The "best" approach remains context-dependent, emphasizing the iterative nature of software development and repository management.

The above is the detailed content of From a Single Repo, to Multi-Repos, to Monorepo, to Multi-Monorepo. For more information, please follow other related articles on the PHP Chinese website!