monorepo

[KaiVolland]

Why are we considering this?

• Applying changes to multiple repositories is cumbersome

• General changes (workflows, basepackages (typescript, vite, ...)) need many changes in several packages

• complexity of compatible versions

• Pro

  • general maintenance and release workflows will be simplified by a lot

• Con

  • access management will not be as granular as it is with single repositories
  • outdated or less used parsers will need updates too

Alternatives:

• Shared configs
• Maintenance Agents?

Take away:

@jansule will try to create a small sample with some basic repositoires during the CodeSprint

[jansule]

Current findings

PoC repository: https://github.com/jansule/monorepo-test

• Packages can be added one by one
• Every package can have their own configurations
  • no need to harmonize directly but makes sense in the future for most benefit
• Shared configurations easily set up
  • possibility of extending shared configurations in packages where needed -> flexibility still given
• Shared workflows
  • release pipeline, commitlint, etc. all only done once
  • pipelines need to be smart enough so that they are still performant
  • UPDATE: I added a simple pipeline incl. a very basic custom github action that does the checks for us. In our case the complexity of dependencies is quite simple, i.e. every parser depends on geostyler-style, no parser depends on any other parser.
• Shared dev dependencies
  • common versions of dependencies (vite, typescript, eslint, etc.)
  • only configured once
  • BUT: changes need to be adjusted everywhere at once
• Shared github issue templates etc.
• Development simplified
  • common npm commands
  • package linking done automatically

Downsides:

• initial kickoff time consuming
• harmonization of packages time consuming (even though not strictly needed at first)

Unclear:

• how to handle bun and npm packages?
• what about commit history, when "merging" multiple repositories into one?
• reuse existing repo (e.g. geostyler-style) vs create new repository?
• what about issues / PRs?
  • issues can be moved
  • PRs: bugfixes and features should be merged before, dependency PRs low priority
• are there repositories with conflicting gh-pages?

What should be included in the monorepo?

Should be included

• geostyler-style
• geostyler-style-parsers

Should NOT be included (left as-is)

• geostyler-data
• geostyler-data-parsers
• geostyler toolings (incl. geostyler UI)

Versioning

• Versioning will stay is as -> sticking to strict semver versioning

Does it solve the pain points?

Applying changes to multiple repositories is cumbersome

Solved. We can make atomic commits throughout multiple packages all reflecting a common change, e.g. adding a property in geostyler-style and directly implementing it in the parsers.

General changes (workflows, basepackages (typescript, vite, ...)) need many changes in several packages

Partially. Workflows and common dev dependencies can be managed centrally. However, breaking changes need to be directly reflected in all included packages, when updating dev dependencies. This might lead to a higher workload, but also directly solves the problems on all included packages.

complexity of compatible versions

Not when sticking to strict semver. However, there are other solutions like compatibility matrices than might even be added to the release notes. See also https://ocruze.github.io/geostyler-compatibility as a proof of concept.

How can we kickoff the monorepo?

• possible to setup monorepo in parallel to existing repos?
• Do we need a dedicated sprint for kicking-off the monorepo approach? Funding?

Verdict

We should follow monorepo approach, since currently, the benefits outweigh the downsides. There are still details to be solved, as well as organizational aspects such as finding the time to kick this off.