diff --git a/design/20230302.gomod.md b/design/20230302.gomod.md index feeadb0aa..e0d3f79f5 100644 --- a/design/20230302.gomod.md +++ b/design/20230302.gomod.md @@ -1,9 +1,59 @@ # Design: More Modules -NB: This design doc follows from a Hackathon by @SgtCoDFish and @inteon. The intention here is to describe what we did -and what we discovered, with an eye to seeking consensus and merging upstream. +NB: This design doc follows from a Hackathon by [@SgtCoDFish](https://github.com/SgtCoDFish) and [@inteon](https://github.com/inteon). -## Problem Statement +The intention here is to describe what we did and what we discovered, with an eye to seeking consensus and merging upstream. + +## In Short + +### Assumptions / Axioms + +- It's hard or impossible to upgrade our dependencies months after a release +- We won't change our conservative approach to backports +- Having fewer dependencies in our go modules is a good thing +- It's OK if people can't import our binaries as go modules + +### Solution + +- Create a go module for each binary +- Create go modules for integration and e2e tests +- Utilise local replace statements where possible + - i.e. Binaries have a local replace for the core cert-manager module + - This breaks imports of those binaries but means changes only require one PR + +### Pros + +- Each binary can be patched independently + - Side effects of a patch are limited to one binary when only that binary has the dependency + - This includes forking a dependency or needing to `replace` one + - Gives us more control over our own destiny + +- Core go.mod dependencies are reduced + - All importers of `github.com/cert-manager/cert-manager` have fewer transitive dependencies + - Reduced chance of dependency conflicts for all importers + - Including us - in subprojects! + - Many people need to import cert-manager! (pkg/apis, etc). + - We might split things more in the future - this is a good first step + +- Lays the groundwork for further splitting out binaries / packages + - This is the start of what we'll do if we want cmctl to be its own repo + - Or splitting `pkg/apis` into a separate module + - Or splitting issuers into a module (to isolate cloud SDK dependencies) + +### Cons + +- Using local `replace` statements for binaries will break imports for those binaries + - We assume this won't be too destructive in most cases + - If we need to make binaries importable again, we can change them to use regular import statements + - That would require two PRs in the event that we need to change the binary + the core module at the same time + - If the binary would've ended up in a separate repo anyway (e.g. cmctl) we'd have done this eventually + +- Increased complexity in working with the codebase + - E.g. `go test ./...` no longer tests _everything_, since it won't recurse into modules + - This can be alleviated with some Makefile work - `make test` can still test everything + - Go Workspaces (`go.work`) can also help in development environments to make things simpler + +## Longer Form Problem Statement **In short:** Some of our dependencies are complex which makes them hard to upgrade in already-released versions