Merge pull request cert-manager#6094 from SgtCoDFish/proliferation_3

Attempt to clarify in short the modules proliferation design

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