[ADR] Group projects together in a monorepo
- pascal wilbrink
- Sander Jansen
Context
It turns out that putting everything in a separate repositories has too many disadvantages e.g.:
- Key management
- User rights
- Doing updates (e.g. library updates need to be done over multiple )
- ES lint rules
The initial idea was that this will help the maintenance of the software. It turns out that a maintainer has a group of repository in practice.
Decision
For OSCD-Components, we should make use of the Package-based Repo. Each component has it's own `package.json` File and can be individually developed, tested, compiled and published.
Motivations to run with a monorepository instead of seperate repositories
- One code owner to rule them all
- One storybook for easy checking/testing components
- 1 NPM token
- Easy copying
- Lower workload on the developers
- 1 ESlint
Technology
A good approach for monorepos is [`Lerna`](https://lerna.js.org/), in combination with [`Nx`](https://nx.dev). Other possible tools are [`TurboRepo`](https://turbo.build/) and [`Rush`](https://rushjs.io/).
Factors to consider to group components in the same repository:
- Shared functionality
- Synergy
- Maintainability
- Activity
It's good to know that a monorepository is not the same as a monolith.
✋ Monorepo ≠ is different fromMonolith
A good monorepo is the opposite of monolithic! Read more about this and other misconceptions in the article on [“Misconceptions about Monorepos: Monorepo != Monolith”](https://blog.nrwl.io/misconceptions-about-monorepos-monorepo-monolith-df1250d4b03c "Misconceptions about Monorepos: Monorepo != Monolith").
There are 3 types of monorepos:
* Integrated Repos
* Package-based Repos
* Standalone Apps
Codeowners can be used to separate the owners of different components.
Core plugins can be grouped together in multiple monorepos
| Plugin | Group | Repository |
|---|---|---|
| @openscd/oscd-open | File-handling | |
| @openscd/oscd-new | File-handling | |
| @openscd/oscd-save | File-handling | |
| @openscd/oscd-validate-template | Validating | |
| @openscd/oscd-validate-schema | Validating | |
| @openscd/oscd-import-ied | IED | |
| @openscd/oscd-compare-ied | IED | |
| @openscd/oscd-virtual-ied | IED | |
| @openscd/oscd-substation-editor | Editor | |
| @openscd/oscd-ied-editor | Editor | |
| @openscd/oscd-template | - |
Packages using the monorepo approach:
- Material (https://github.com/material-components/material-components-web)
- Shoelace (https://github.com/shoelace-style/shoelace)
- Helsinki Design System (https://github.com/City-of-Helsinki/helsinki-design-system)
- NL Design System (https://github.com/nl-design-system/example)
- Etc.
Consequences
Disadvantages for combining different packages into a monorepo
- A monorepo has less authorization rules.
- If you can access one package in the monorepo, you can access them all
- Git history will become more cluttered in a monorepo
- Maintainer ship on a single package in a monorepo can become more of a hassle
- 1 maintainers for all compontents (mitigation: can be splitup in multiple mono repositories to make it manageble)
- Risk of overlapping (migitation: can be enforced by Lerna)