ReleaseKit/docs/roadmap/module-releases.md

# Roadmap: release individual Go modules

Status: planned feature; open recommendations await resolution.

## 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
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.

## Current baseline

The baseline is ReleaseKit v0.3.0 plus accepted ADR 0005; module selection is
not implemented.

- `ReleaseRequest` selects a repository, product, and version. `Candidate` and
  `PublicationResult` expose the version without a distinct module or tag name.
- Candidate capture reads `docs/releases/<version>.md` from the captured commit.
  Local and remote uniqueness checks, tag creation, push, and reconciliation use
  the version as the Git tag.
- The shared validation path runs tests, selected vet, and package compilation
  from the repository directory. Optional content checks inspect the committed
  repository tree, including nested-module contents.
- Profiles support shared validation and additional commands. CLI product
  checks run from the repository directory with candidate/version context.
- Artifact builds and delivery also use repository/version assumptions. The
  consumer Woodpecker template selects `refs/tags/v*` and bootstraps ReleaseKit
  from repository-root module files.

The existing candidate capture, declarative validation, exact-object publication,
and outcome reporting provide the foundation. Scope and identity need to be
carried through those paths together.

## Targeted end state

An invocation selects one module and one semantic version. Omitted selection
means the repository-root module. For example:

| Selected directory | Semantic version | Complete tag | Committed release note |
| --- | --- | --- | --- |
| Root | `v0.1.0` | `v0.1.0` | `docs/releases/v0.1.0.md` |
| `integrations/ckconfig` | `v0.2.0` | `integrations/ckconfig/v0.2.0` | `integrations/ckconfig/docs/releases/v0.2.0.md` |
| `integrations/ckprompt` | `v0.1.0` | `integrations/ckprompt/v0.1.0` | `integrations/ckprompt/docs/releases/v0.1.0.md` |

All mandatory and selected optional release checks use the selected module's
scope. Independently released nested modules are excluded from their parent's
validation inputs. Checks may read referenced material elsewhere in the
captured repository without adding that material's surrounding files to the
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.

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.

## Work needed

### 1. Establish a shared module and release identity

**Rationale:** One resolved identity prevents checks and publication from using
different interpretations of the selected module or tag.

**Target:** Distinct repository directory, module directory, semantic version,
and complete tag are available throughout candidate handling and public evidence.

**Work:** Add an optional repository-relative module selection to the public
request and profile, with root defaults. Resolve it against the captured
repository and committed module declaration. Derive tags using Go's standard
module conventions, including major-version directories: a `/v2` module stored
at `integrations/ckconfig/v2` uses `integrations/ckconfig/v2.0.0` for `v2.0.0`.
Carry the resolved identity through facade conversions, internal requests,
callbacks, results, and CLI diagnostics. Keep semantic-version validation
separate from full-tag handling. Exact field names belong in API design.

### 2. Apply one validation scope

**Rationale:** Consumers should select the release unit once and receive
consistent validation across enabled checks.

**Target:** Tests, vet, package compilation, formatting, distribution checks,
file-size checks, Markdown, and product-check context all correspond to the
selected module and its relevant release materials.

**Work:** Give the existing shared validation path both repository context and
module scope. Run Go commands in the module directory with the existing offline
and workspace-disabled environment. Select committed file inputs once under the
agreed boundary convention and apply that selection to each content check.
Retain repository access for resolving Markdown destinations and existing
committed-file references. A link to another module may be checked for existence
or its target heading without scanning that module's unrelated documents.

Update module-distribution inspection to examine the selected release's inputs.
For example, an unrelated sibling's filesystem replacement should not fail the
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.

### 3. Bind notes and publication to the resolved identity

**Rationale:** Different modules can use the same semantic version while
publishing distinct source identities and release notes.

**Target:** The selected module's committed note identifies its product and
semantic version. Publication and recovery address its complete tag.

**Work:** Resolve module-local note paths and retain existing title validation
and captured note bytes. Thread the complete tag through local guards, remote
guards, annotated-tag creation, exact-object push, and bounded reconciliation.
Include the module, version, and resolved tag in success and failure evidence
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

**Rationale:** The shared release operation should replace consumer publication
logic with small per-module declarations.

**Target:** A shared launcher can select a profile and pass a semantic version;
API consumers express the equivalent operation. Additional checks receive
module context and repository context for explicit composition work.

**Work:** Map profile selection into the shared request, document relative-path
behavior, and provide module/tag context to configured commands. Retain existing
profile selection through `--config`; a separate CLI override for the module is
not needed to satisfy the initial request. Add a maintained multi-module example
showing root and integration profiles and a small shared launcher. Show dependency
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

**Rationale:** This changes release identity and validation boundaries, including
the behavior of root modules with nested modules.

**Target:** Representative public API and CLI workflows establish that the
selected module is validated and only its intended tag is published.

**Work:** Extend existing behavioral tests using local repositories and remotes.
Cover root defaults; nested-module failure while the root suite passes; equal
versions across modules; major-version directories; full-tag reuse; and failed
or unknown publication with the correct recovery identity. Exercise optional
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.

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
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

### 1. How should nested module boundaries be recognized?

**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.

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.

**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.

### 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
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.

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.

**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.

### 3. Should nested-module builds and hosted delivery ship with publication?

**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.