From 8ee8b0aec058c93c85047e6f5234bffa16938c6e Mon Sep 17 00:00:00 2001 From: Elijah Duffy Date: Sun, 25 Oct 2026 14:47:17 -0700 Subject: [PATCH 1/2] docs: propose module versioning boundaries --- AGENTS.md | 4 +- ...odule-and-nest-heavy-dependency-modules.md | 50 +++++++++++++++++++ 2 files changed, 52 insertions(+), 2 deletions(-) create mode 100644 docs/adr/20261025T214616275Z-version-light-core-packages-in-the-root-module-and-nest-heavy-dependency-modules.md diff --git a/AGENTS.md b/AGENTS.md index 3fd1e35..fd84e06 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,7 +6,7 @@ - Documentation: `go run ./cmd/docs check`; create records with `go run ./cmd/docs new adr|plan "Title"`. This checker repository uses its local implementation as the source of truth. ## Scope and decisions -- Before editing under a directory with its own AGENTS.md, read it. Scoped files: none; this root governs the single Go module. +- Before editing under a directory with its own AGENTS.md, read it. Scoped files: none currently; this root governs the repository, including nested Go modules unless nearer instructions override it. - Explicit user instructions win; nearer scoped rules override broader rules. - Distinguish confirmed requirements, proposed defaults and unresolved decisions; resolve material ambiguity before dependent work. - Proposed ADRs are context, not authority; read relevant accepted decisions before changing their scope. @@ -30,7 +30,7 @@ Go module `go.auvem.com/corestack`. - Docs format (the spec `docs check` implements): `docs/docs-format.md`. - Decisions live in `docs/adr/`, plans in `docs/plans/`. Records are permanent; never rename them. -- Dependencies are limited to `go.yaml.in/yaml/v3` and `github.com/yuin/goldmark`. +- Add dependencies only to the module that needs them; heavy dependencies go in nested modules (see the [proposed module-boundary ADR](/docs/adr/20261025T214616275Z-version-light-core-packages-in-the-root-module-and-nest-heavy-dependency-modules.md)). ## Go - Default backend language is Go; follow existing package boundaries. diff --git a/docs/adr/20261025T214616275Z-version-light-core-packages-in-the-root-module-and-nest-heavy-dependency-modules.md b/docs/adr/20261025T214616275Z-version-light-core-packages-in-the-root-module-and-nest-heavy-dependency-modules.md new file mode 100644 index 0000000..4dce866 --- /dev/null +++ b/docs/adr/20261025T214616275Z-version-light-core-packages-in-the-root-module-and-nest-heavy-dependency-modules.md @@ -0,0 +1,50 @@ +--- +title: "Version light core packages in the root module and nest heavy-dependency modules" +date: 2026-10-25 +status: proposed +implementation: not-started +summary: Keep light core packages on root-module versions and isolate heavy or independently versioned packages in nested modules from their first commit. +tags: + - modules + - versioning +supersedes: [] +superseded_by: [] +related: [] +tracking: + - https://gitea.auvem.com/corestack/go/issues/2 +implemented_by: [] +--- + +# Version light core packages in the root module and nest heavy-dependency modules + +## Context and Problem Statement + +The repository currently has one Go module, `go.auvem.com/corestack`. A plain `vX.Y.Z` tag versions every package in that module together and triggers a release of the `docs` binary. Light core packages can share this version stream and one changelog per tag; packages with heavy dependencies or independent release needs benefit from their own module boundaries. + +Carving a package out after it has shipped in the root module is the expensive case: older root versions still contain it, while the new nested module supplies the same import path. Consumers can encounter ambiguous imports until coordinated releases and dependency upgrades remove the overlap. Starting a package as a nested module from its first commit avoids that migration. + +The fixed dependency list in AGENTS.md described only the docs checker. It would block the planned Bob and Goose dependencies for `page` and `migrate`; dependency placement needs a module-boundary rule instead of a repository-wide allowlist. + +## Considered Options + +* Keep every package in the root module: simplest releases, but couples heavy and independently versioned packages to core releases and makes later extraction costly. +* Give every package a nested module immediately: avoids later extraction, but adds module and release bookkeeping to light core packages that can share a version. +* Keep light core packages in the root module and start heavy or independently versioned packages as nested modules: retain simple core releases while avoiding the costly extraction case. + +## Decision Outcome + +Choose the mixed boundary: light core packages share the root module; heavy-dependency or independently versioned packages begin as nested modules. + +* Root module, plain `v*` tags: `lifecycle`, `lifecycle/cli`, `migrate`, `page`, and `cmd/docs`. They share one version stream and one changelog per root tag. Before 1.0, breaking changes use minor version bumps. +* Nested modules from their first commit: `gql`, `connect`, and any future package that brings heavy dependencies, such as gqlgen or protobuf, or is likely to need independent versioning. Each has its own `go.mod` and directory-prefixed tags, for example `gql/v0.1.0` and `connect/v0.1.0`. +* Add dependencies only to the module that needs them. The named core packages remain in the root module; heavy dependencies belong in the relevant nested module. +* Keep `cmd/docs` in the root module. The [release workflow](/.gitea/workflows/release.yml) listens only for plain `v*` tags, and [GoReleaser](/.goreleaser.yaml) builds `./cmd/docs`, so only root-module tags publish binaries. Prefixed library tags never publish binaries. + +This proposal records the boundary before the planned packages are added; it does not create empty modules or change the current release configuration. + +### Consequences + +* Light core packages retain coordinated versions and releases. Consumers do not compile dependencies of packages they do not import; module graph pruning helps limit the dependency graph they load. +* Heavy-dependency and independently versioned packages avoid overlapping ownership of an import path with older root-module versions. +* Each nested module needs its own dependency maintenance, checks, and prefixed release tags. That bookkeeping is reserved for packages that need the boundary. +* Root-module consumers share version bumps even when only another core package changes. Moving a shipped root package into a nested module later still requires coordinated releases and consumer upgrades. -- 2.54.0 From 104c3ec7579adc93018513ada1fd9b50e47cea20 Mon Sep 17 00:00:00 2001 From: Elijah Duffy Date: Mon, 26 Oct 2026 21:44:09 -0700 Subject: [PATCH 2/2] docs: accept module versioning boundaries --- AGENTS.md | 2 +- ...-the-root-module-and-nest-heavy-dependency-modules.md | 9 +++++---- 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index fd84e06..9b1ce1e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -30,7 +30,7 @@ Go module `go.auvem.com/corestack`. - Docs format (the spec `docs check` implements): `docs/docs-format.md`. - Decisions live in `docs/adr/`, plans in `docs/plans/`. Records are permanent; never rename them. -- Add dependencies only to the module that needs them; heavy dependencies go in nested modules (see the [proposed module-boundary ADR](/docs/adr/20261025T214616275Z-version-light-core-packages-in-the-root-module-and-nest-heavy-dependency-modules.md)). +- Add dependencies only to the module that needs them; heavy dependencies go in nested modules (see the [module-boundary ADR](/docs/adr/20261025T214616275Z-version-light-core-packages-in-the-root-module-and-nest-heavy-dependency-modules.md)). ## Go - Default backend language is Go; follow existing package boundaries. diff --git a/docs/adr/20261025T214616275Z-version-light-core-packages-in-the-root-module-and-nest-heavy-dependency-modules.md b/docs/adr/20261025T214616275Z-version-light-core-packages-in-the-root-module-and-nest-heavy-dependency-modules.md index 4dce866..628c1ce 100644 --- a/docs/adr/20261025T214616275Z-version-light-core-packages-in-the-root-module-and-nest-heavy-dependency-modules.md +++ b/docs/adr/20261025T214616275Z-version-light-core-packages-in-the-root-module-and-nest-heavy-dependency-modules.md @@ -1,8 +1,8 @@ --- title: "Version light core packages in the root module and nest heavy-dependency modules" date: 2026-10-25 -status: proposed -implementation: not-started +status: accepted +implementation: implemented summary: Keep light core packages on root-module versions and isolate heavy or independently versioned packages in nested modules from their first commit. tags: - modules @@ -12,7 +12,8 @@ superseded_by: [] related: [] tracking: - https://gitea.auvem.com/corestack/go/issues/2 -implemented_by: [] +implemented_by: + - https://gitea.auvem.com/corestack/go/pulls/4 --- # Version light core packages in the root module and nest heavy-dependency modules @@ -40,7 +41,7 @@ Choose the mixed boundary: light core packages share the root module; heavy-depe * Add dependencies only to the module that needs them. The named core packages remain in the root module; heavy dependencies belong in the relevant nested module. * Keep `cmd/docs` in the root module. The [release workflow](/.gitea/workflows/release.yml) listens only for plain `v*` tags, and [GoReleaser](/.goreleaser.yaml) builds `./cmd/docs`, so only root-module tags publish binaries. Prefixed library tags never publish binaries. -This proposal records the boundary before the planned packages are added; it does not create empty modules or change the current release configuration. +This decision establishes the boundary before the planned packages are added. The rule is implemented in [AGENTS.md](/AGENTS.md), and the existing release configuration already follows it. Future packages apply the rule when introduced; no empty modules are needed. ### Consequences -- 2.54.0