diff --git a/docs/roadmap/module-releases.md b/docs/roadmap/module-releases.md index 05ebb51..3d642e4 100644 --- a/docs/roadmap/module-releases.md +++ b/docs/roadmap/module-releases.md @@ -1,18 +1,18 @@ # Roadmap: release individual Go modules -Status: planned feature; open recommendations await resolution. +Status: planned feature; scope decisions resolved. ## Purpose -Implement [ADR 0005](../adr/0005-module-release-scope.md) so a consumer can check -and publish one selected Go module in a shared repository through ReleaseKit's -API and CLI. CommandKit's core and optional integrations provide the initial +Implement [ADR 0005](../adr/0005-module-release-scope.md) so a consumer can check, +publish, build, and deliver one selected Go module in a shared repository through +ReleaseKit's API and CLI. CommandKit's core and optional integrations provide the initial consumer case. Each invocation should require only module selection, product settings, and a semantic version, with ReleaseKit owning the common mechanics. This roadmap describes the target and the work from the current baseline. It does not select a ReleaseKit release version or prescribe a staged implementation -plan. Recommendations under Open Decisions are proposals, not accepted contracts. +plan. The decisions recorded below govern the planned scope. ## Current baseline @@ -57,13 +57,16 @@ input set. The checkout remains the boundary for outside-checkout link checks. Repository cleanliness, branch, candidate commit, remote endpoint, and publication guards remain repository-wide. The complete selected tag governs uniqueness, publication, and recovery. A successful source-tag push remains completion. -Dependency preparation and sibling release ordering remain consumer activities. +Consumers prepare dependencies before offline candidate validation and choose +sibling release ordering. Dependency preparation for delivery targets the +selected module through the existing preparation operation when needed. The feature covers individual releases. Batch publication, automatic release selection, dependency-driven versioning, and arbitrary tag templates remain -outside this roadmap. Artifact and hosted-delivery integration is an open scope -decision below. This work adds no consumer-installation, proxy-availability, CI, -or hosted-delivery completion gate. +outside this roadmap. Artifact builds, hosted delivery, and CI use the same +selected module and release identity. Delivery remains asynchronous and supports +both page-only and binary profiles. This work adds no consumer-installation, +proxy-availability, CI, or hosted-delivery publication completion gate. ## Work needed @@ -107,8 +110,7 @@ selected module's check. Determine relevant shared release materials through existing conventions; shared files should not pull in an entire parent tree. Keep the optional checks optional and retain their existing individual rules, error identities, cancellation, and cause propagation apart from the intended -scope change. Resolve boundary identification and path conventions below before -finalizing these contracts. +scope change. Apply the boundary and path conventions recorded below. ### 3. Bind notes and publication to the resolved identity @@ -126,7 +128,52 @@ as available, alongside commit, endpoint, phase, state, and tag object. Preserve the existing publication outcomes and repository checks. Root notes and tags retain their ordinary forms. -### 4. Make API and CLI adoption small and coherent +### 4. Carry module identity through builds and delivery + +**Rationale:** A selected module should mean the same release unit throughout +ReleaseKit's supported operations. + +**Target:** Standalone builds, candidate build checks, direct delivery, and +prebuilt-asset delivery all operate on the selected module. Hosted pages use +its complete tag and module-local note; binaries report its semantic version. + +**Work:** Extend build and delivery requests and profile mapping with the shared +module identity. Resolve main packages and module-owned build paths from the +module directory. Prepare build dependencies there, and preserve existing offline +artifact compilation and version smoke checks. Carry module identity through +build results and receipts so prebuilt delivery verifies the selected module, +version, tag where applicable, candidate commit, settings, and artifact hashes. +Keep ordinary local builds usable without requiring a published tag. + +Use the full tag for tagged-checkout verification, Gitea release lookup and +creation, and source links. Use the semantic version for binary version injection +and module release titles. Select the module-local note and retain existing +page/asset conflict, retry, and partial-delivery behavior. Test source URLs with +slash-containing tags. Distinct module tags can have separate Gitea pages at the +same commit. A page-only profile continues to require no application binary. +Review receipt compatibility deliberately and document any required migration. + +### 5. Support module-aware CI delivery + +**Rationale:** Local operations and tagged-source delivery need the same module, +profile, and version selection. + +**Target:** The maintained consumer workflow accepts root and nested-module tags, +selects the corresponding profile, and delivers only that module's release. +Tool selection follows the tagged module configuration under +[ADR 0004](../adr/0004-module-selected-tooling.md). + +**Work:** Extend tagged-checkout preparation and `ci-deliver` to distinguish the +full event tag from the semantic version. Adapt tag filters, profile selection, +tool bootstrap, and application dependency preparation. Use an explicit +module/profile mapping or equivalent small consumer declaration; keep the +selection consistent with the derived tag. Verify the event commit before tool +bootstrap and use the tagged source's selected module files on retries. +Preserve temporary bootstrap metadata and existing credential handling. Cover +major-version directory layouts without assuming that trimming the tag always +identifies the physical module directory. Include page-only and binary examples. + +### 6. Make API and CLI adoption small and coherent **Rationale:** The shared release operation should replace consumer publication logic with small per-module declarations. @@ -144,7 +191,7 @@ preparation before offline validation and sequential sibling releases when a dependency version must be published first. Keep product checks focused on consumer assertions instead of repeating the standard suite. -### 5. Verify and document the complete behavior +### 7. Verify and document the complete behavior **Rationale:** This changes release identity and validation boundaries, including the behavior of root modules with nested modules. @@ -160,82 +207,56 @@ checks with violations inside and outside the selected scope, parent selection excluding independent nested modules, and cross-module Markdown references. Verify that repository guards still observe changes outside the selected module and that module selection does not repeat the standard suite. Reuse existing -failure tests where they already protect unchanged behavior. +failure tests where they already protect unchanged behavior. Add representative +nested-module build/version-injection, receipt ownership, Gitea page/asset, and +CI tag/profile/tool-selection coverage. Use local HTTP servers for delivery and +isolated synthetic module proxies for bootstrap tests. Verify that retries use +the original module selection and full tag after the default branch changes. -Update GoDoc, CLI/configuration references, check/publication guides, adoption -examples, and recovery guidance together. Explain root-module scope changes in -the release note and migration guidance. Document semantic version versus full +Update GoDoc, CLI/configuration references, check/publication/build/delivery guides, +adoption examples, CI templates, and recovery guidance together. Explain root-module +scope changes in the release note and migration guidance. Document semantic version versus full tag in note titles and source/licensing links. ReleaseKit's own maintainer policy continues to describe its root-module release; consumer guidance explains how multi-module consumers adapt their policies. Run the normal offline suite and public API checks for implementation changes; validate documentation links and examples. Synthetic dependency fixtures use isolated module caches. -## Open Decisions +## Resolved decisions -### 1. How should nested module boundaries be recognized? +### Module boundaries -**Recommendation:** Use committed nested `go.mod` locations as module boundaries -for ordinary source directories. This follows Go's module structure and avoids -a second registry of independently versioned products. Specify treatment of -vendored content and fixture modules before implementation: vendored material -remains part of the selected module's file-check inputs, while nested fixture -modules can be exercised through the parent's tests or product checks. A -repository-level workspace file outside a selected nested module's scope would -not fail that module's workspace-file check merely because it exists. +Use committed nested `go.mod` locations as module boundaries for ordinary source +directories. This follows Go's module structure and avoids a second registry of +independently versioned products. Vendored material remains part of the selected +module's file-check inputs. Nested fixture modules are excluded from generic +parent file checks and can be exercised through the parent's tests or product +checks. Document this distinction and verify representative cases. -The tradeoff is that a nested fixture module can be excluded from generic file -checks even when it has no independent release. That distinction needs clear -documentation and representative tests. +A repository-level workspace file outside the selected nested module's scope +does not fail that module's workspace-file check merely because it exists. +Shared release materials and referenced destinations receive the targeted +inspection described above. -**Alternative:** Declare independently released module directories explicitly -and exclude only those boundaries. This distinguishes products from fixtures -precisely and keeps fixture files in their parent's generic validation. It adds -a declaration consumers must maintain and coordinate with their module layout. -It is viable if real consumers need that distinction enough to justify the -configuration. +### Relative paths and product commands -### 2. Which directory anchors relative paths and product commands? - -**Recommendation:** Anchor module selection and profile lookup at the repository; -anchor module-owned validation settings, such as file-size exclusions, and +Anchor module selection and profile lookup at the repository. Anchor +module-owned validation and build paths, including file-size exclusions, and configured product-command execution at the selected module. Keep diagnostic file paths repository-relative and expose both directories to product commands. -Markdown destinations remain relative to their source documents. This makes a -per-module profile self-contained while retaining unambiguous findings. +Markdown destinations remain relative to their source documents. -Existing root profiles retain their meaning. Nested-module launchers would use -the provided repository context when invoking shared scripts. Document these -rules together rather than adding a path-base switch to each check. +Existing root profiles retain their meaning. Nested-module launchers use the +provided repository context for shared scripts. These conventions keep +per-module profiles self-contained without adding per-check path-base switches. -**Alternative:** Keep configuration paths and product-command execution -repository-relative, while shared check inputs remain module-scoped. This -preserves the current conventions and makes shared script invocation direct. -It requires module prefixes in otherwise module-specific settings and makes -moving or copying profiles more cumbersome. Both choices can implement the -accepted validation scope. +### Complete operation support -### 3. Should nested-module builds and hosted delivery ship with publication? +Implement module selection across checking, publication, artifact builds, +hosted delivery, and CI in this feature. The target is a coherent release API +for root and nested modules. CommandKit's current source-only use supplies an +adoption case while the feature supports the full existing release workflow. -**Recommendation:** Deliver the requested source-only `Check` and `Publish` -capability first. Keep existing root build/delivery workflows working and document -the supported boundary. For that initial increment, report an unsupported -nested-module artifact-build request before validation or publication rather -than building the root product under the nested module's release identity. -This proposed limitation requires an explicit scope decision; it is not imposed -by ADR 0005. Package compilation remains part of module validation and is covered -by this roadmap. - -This meets CommandKit's immediate need with a focused change, at the cost of -requiring follow-up work for consumers needing nested-module artifacts or hosted -pages. Review shared profile handling so unsupported delivery paths do not -silently interpret a nested module as the root product. - -**Alternative:** Extend artifact builds and hosted delivery in the same release. -This gives every release operation the same module model immediately. It adds -work on build paths, semantic-version injection, receipts, tag verification, -note/source URLs, dependency preparation, and CI profile/tool selection. The -maintained tag filter and root-only bootstrap also need adaptation. This is a -viable cohesive release if those consumers are ready; it expands the sprint -beyond the source-only publication request. Delivery remains asynchronous under -either choice. +Implementation may proceed in stages; feature completion includes all of these +operations. Existing single-module defaults and the separation between source +publication and asynchronous delivery remain in place.