# Pending notes for the next release

Status: pending release preparation. This feature does not select a release
version or move this draft to `docs/releases/<version>.md`.

## Release individual Go modules

ReleaseKit operations can now select one Go module within a Git repository.
Omitted module selection retains the repository-root default. A selected module
is identified by both its repository-relative physical directory and its own
declared module path. ReleaseKit derives a semantic version's complete Git tag
from that identity, including Go's `/v2` major-version convention. For example,
`v2.1.0` for a module declared as `example.com/project/integrations/core/v2`
uses `integrations/core/v2.1.0`, whether the module is physically stored at
`integrations/core` or `integrations/core/v2`. Its release note stays at the
physical module's `docs/releases/v2.1.0.md` path.

The public `Check`, `Publish`, `Build`, and `Deliver` requests add `ModuleDir`;
results expose the resolved module directory, declared module path, and complete
tag alongside existing commit and outcome evidence. `Version` remains the
stable semantic version used in note titles, binary version output, and asset
names. Git publication and hosted delivery use the complete tag. Product
commands receive both repository and module paths, and candidate callbacks
receive the module identity.

`ValidationSpec.SharedFiles` and profile `validation.shared_files` allow a
repository-relative list of committed shared files to join optional file
checks. Omission or `null` selects the available root `COPYRIGHT`, `LICENSE`,
and `docs/oss/attribution.md` defaults; an explicit list replaces those
defaults, and `[]` selects none. Explicit files must exist even when file
checks are disabled. This selection does not enable a check.

Profiles add `module_dir` for physical module selection. The CLI's `ci-deliver`
now takes a full Git `TAG`; its final path component supplies the semantic
version. The optional `--prepared` mode verifies an already prepared checkout
without fetching or checking it out again. `--expected-module` binds a mapped
launcher selection to the selected profile. The public tagged-checkout request
renames `Version` to `Tag` and adds `VerifyOnly`; dependency preparation now
takes a `DependencyPreparationRequest` with repository and module directories.
`DeliveryRequest.ExpectedTag` binds delivery to the exact CI event tag before
building artifacts or contacting Gitea.

The private `.releasekit-build.json` receipt now requires schema version 1 and
binds artifacts to the module directory, declared module path, semantic
version, complete tag, source commit, normalized build settings, and artifact
declarations. Older and unversioned receipts are rejected; rebuild with the
updated `build` command before using `deliver --assets DIR`.

Relative `build --output DIR` and `deliver --assets DIR` paths both use the
selected module directory. Nested-module consumers can use the same relative
directory for building and retrying delivery; absolute directories remain usable.

The maintained [multi-module example](../../examples/multi-module/) shares a
four-column `release-modules.tsv` and POSIX selector between its local launcher
and mapped Woodpecker workflow. The workflow verifies and detaches the triggering
tag before reading the mapping, profile, module files, or ReleaseKit version.
Retries therefore use the original tagged source after the default branch
changes. Root-only consumers can keep the ordinary profile and the simpler
[root tag workflow](../../examples/woodpecker/tag-delivery.yml) without a map.

## Consumer migration

Update callers, profiles, receipts, and CI declarations together for this
clean interface cutover; compatibility shims and legacy receipt readers are
not provided.

- Set `ModuleDir` in Go requests or `module_dir` in profiles for a nested
  module. The selected directory must contain its own `go.mod`; module paths
  and release tags are read from that declaration, not inferred from a folder
  name. Keep `Version` as a semantic version in ordinary commands and API calls.
- Update reads of result identity to use `ModuleDir`, `ModulePath`, and `Tag`
  where needed. Product commands can use `RELEASEKIT_REPOSITORY_DIR` and
  `RELEASEKIT_MODULE_DIR` to distinguish repository-level work from
  module-local checks.
- Replace `TaggedCheckoutRequest.Version` with the complete `Tag`. Set
  `VerifyOnly` when a bootstrap step already verified and detached the event
  checkout. Change `PrepareBuildDependencies` calls to pass a
  `DependencyPreparationRequest`.
- Add `module_dir` and, when needed, `validation.shared_files` to profiles.
  Recheck profile-relative and repository-relative paths. Prepare and commit
  each binary module's `go.sum` before tagging so dependency preparation leaves
  the tagged source clean for delivery verification.
- Change `ci-deliver VERSION` invocations to pass the full event `TAG` and
  required `--commit OID`. Maintained bootstraps should use `--prepared` after
  verifying the tag and commit. A mapped launcher should pass
  `--expected-module DIR`; the profile remains the source of selection.
- Regenerate existing build receipts with the new `build` command before
  prebuilt delivery. Do not edit old receipts into the new format.
- Root-module validation now excludes independently released nested modules
  from module-scoped file checks. Run a nested module's checks from that module
  when it is the release unit. Nested module fixtures remain available to the
  parent module's product tests.

ReleaseKit's current consumer minimum remains Go 1.26.0. Root-module releases
retain their existing note path, unprefixed tags, profile defaults, and small
root-only workflow. A successful push of the intended source tag remains the
source-release completion point; hosted page and asset delivery remains
asynchronous and may be retried from the same immutable tag. No live-service,
deployment, or consumer-rollout gate is introduced.

For current behavior, see the [API and consumer guides](../consumers/),
[CLI contract](../cli.md), [configuration reference](../config.md),
[Gitea integration](../integrations/gitea.md), and
[ReleaseKit release procedure](../release.md).