Navigating the shift to a monorepo approach

With a monorepo, all the parts—what the software does, its tools, how it's set up, and how to use it-are stored together. It’s like putting together a big puzzle; every piece matters.

In software development, every line of code is part of something bigger. Think of it as making a big web of software, where each part is success of the whole process. Unlike the multi-repo approach, the monorepo approach keeps everything in one place, instead of keeping each part of a project in separate repositories.

Monorepo Approach – The Concept Explained

A monorepo serves as a unified repository, consolidating various project components into a single location. This method stands in contrast to a multi-repo setup, where each component is kept in its own separate repository. 

Consider a software application consisting of modules for business logic, internal libraries, multi-level testing, deployment configurations, documentation, and additional development tools. The development of such an application could utilize either the monorepo or multi-repo strategy.

Which one can serve better? Whether a monorepo is better than a multi-repo depends on the specific needs and context of a project or organization, such as:    

• Size and number of teams working on the project
• Culture of inter-team collaboration
• Solution architecture and technology used
• Release strategy

Switching to a monorepo comes with its share of complexities. While adopting this approach brings many benefits, it also presents certain challenges. 

Advantages of Monorepo Implementation

• Simplified Code Navigation: The application's overall flow can be more easily understood if the entire codebase, including libraries, is consolidated into one place. This feature is especially valuable for new developers, since it allows them to see where the application begins and ends at a glance
• Fewer Merge Requests: Monorepo gives developers more control by allowing multiple changes to be implemented with a single merge request. Whether it be adding feature changes, detecting code inconsistencies, or updating external dependencies across the entire application, this design simplifies the development proces.
• Enhanced Testing: Developing new features becomes more manageable when the entire solution can be tested together. Building the application from scratch using automated scripts is straightforward in a monorepo environment, whereas it presents challenges in a multi-repo setting.
• Living Documentation: Keeping documentation current is always a challenge. However, it becomes easier when the documents are stored alongside the code in one location. This setup makes it less likely to overlook and simpler to update the documents whenever a new feature is released.

Navigating the Challenges

• Complexity in CI/CD Pipelines: Designing an efficient, adaptable CI/CD pipeline is challenging in a monorepo. This task is significantly demanding due to the size of the monorepo, which contains a lot of business logic and libraries as well as a vast array of code. This extensive scale can lead to complex and intricate CI/CD configurations and increased resource demands.
• Managing Organizational Risks: Monorepos are often misunderstood as repositories where every thread of code belongs, regardless of its relevance or functionality. However, without guidelines, the repository will quickly become cluttered and unmanageable. Maintaining order and efficiency depends on establishing and adhering to inclusion criteria.
• Versioning: In a monorepo setup, every piece of code shares the same release tag post-deployment. While simplifying some aspects of project management, can complicate others, particularly when tracking changes or managing releases of individual components within the broader project landscape.

The Falcon V Systems Shift for Streamlined Development Process

At Falcon V Systems, projects experienced significant expansion and increased complexity. Consequently, we transitioned to a monorepo, addressing the need for a more streamlined development process.

Guided by our agile mindset and willingness to experiment, the decision was made to consolidate the scattered repositories of a particular application into a single, unified monorepo. This decision, made out of necessity and forward thinking, began our transformative journey. 

Lessons Learned

One of the most significant challenges we encountered was managing the CI/CD pipeline.

When creating generic CI/CD definitions for multiple modules, keeping them clear, readable, and expandable is challenging. The use of various modules and libraries leads to numerous CI/CD jobs running simultaneously on intended hosts, resulting in high resource consumption and longer pipelines.

This situation prompted several improvements, including the addition of a remote cache. It was also an opportunity to review and optimize tests. Although there is always potential for further enhancement, satisfaction with the current handling of these issues is high. Besides overcoming these challenges, the advantages of a monorepo made a positive impression from the beginning.

A Continuous Journey

Like any solution, monorepo has its advantages and disadvantages. For Falcon V Systems, adopting the monorepo has proved beneficial, but it does not imply that it is the only viable method. Based on our experience, it works well.

The majority of new projects we initiate are now based in a monorepo from the beginning. As a result, we have developed habits and patterns that facilitate smooth project management.

The monorepo approach has not just been a technical adjustment; it has been a cultural shift, fostering a sense of unity and shared purpose among our teams.