# ReleaseKit v0.4.0

## Summary

ReleaseKit supports releasing individual Go modules within a repository, with
module-specific validation, builds, tags, and Gitea release pages. Root-module
consumers retain the simple default configuration. This release also improves
path resolution, offline source inspection, failure diagnostics, and efficiency.

## Changes

- `Check`, `Publish`, `Build`, and `Deliver` accept `ModuleDir` and expose the
  resolved module directory, declared module path, and complete tag in their
  results. Each operation resolves its module identity once. Product commands
  receive repository and module context, and candidate callbacks receive module
  identity.
- Release tags follow the selected module's physical location and declared major
  version. For example, `v2.1.0` for
  `example.com/project/integrations/core/v2` uses
  `integrations/core/v2.1.0` whether its physical directory is
  `integrations/core` or `integrations/core/v2`. Its note remains at that physical
  module's `docs/releases/v2.1.0.md`. Binary version output and asset names retain
  the semantic version; Git publication and Gitea delivery use the complete tag.
- Profiles add `module_dir`. Go checks and configured product commands run from
  the selected module. Automatic committed-file inputs stop at independent
  nested modules; vendored files remain included. Nested fixtures remain
  available to the parent module's product tests.
- `ValidationSpec.SharedFiles` and profile `validation.shared_files` select
  repository-relative literal files for optional file checks. Omission selects
  the available root copyright, license, and attribution defaults; an explicit
  list replaces them, and an explicit empty list selects none. Explicit files
  must exist even with checks disabled. Selection preserves the enabled checks
  and Go test scope; reference inspection can read destinations elsewhere in
  the captured repository.
- Module releases receive separate Gitea pages, including source-only modules.
  Relative build output and prebuilt delivery paths share the selected module
  as their base. Prebuilt receipts bind artifacts to module identity, semantic
  version, complete tag, source commit, and normalized build settings.
- `ci-deliver` accepts the complete event tag. Prepared mode verifies a checkout
  already detached at that tag, and expected-module and expected-tag checks bind
  delivery to the CI selection before building or contacting Gitea. The
  multi-module example shares a module map between its local launcher and
  Woodpecker workflow. The workflow verifies the tag before reading the mapping,
  profile, or tool selection, preserving the tagged configuration for retries.

## Reliability and efficiency

- Operations resolve the containing Git checkout root when invoked from a child
  directory. Working-tree and committed module paths resolve symlinks consistently,
  including paths containing `..`. Committed identity comes from Git objects;
  page-only delivery can use committed module metadata absent from the worktree.
  Valid local main-module paths are accepted.
- Build failures preserve available identity and settings alongside completed
  artifacts. Invalid versions retain the public error identity and the CLI's
  usage-error status. Prebuilt delivery accepts equivalent checkout paths while
  retaining source and module verification.
- Committed release-note and validation reads remain offline in partial clones.
  Validation reads blob contents and sizes as needed for selected inputs and
  referenced destinations. Unavailable blobs outside that inspection scope do
  not prevent applicable checks.
- Module-file selection uses ancestor boundary lookups. Operations reuse Go
  environment discovery while its inputs remain suitable for reuse and acquire
  Go settings only when Go work needs them. Delivery reuses its local asset
  verification when uploading missing assets, removing a repeated hashing pass.

These improvements depend on the repository and workload. Artifact verification,
exact remote comparisons, additive retries, and partial-delivery reporting retain
their behavior.

## Compatibility

This pre-1.0 minor release introduces a clean API and receipt cutover:

- `TaggedCheckoutRequest.Version` becomes `Tag`, containing the complete Git
  tag. `VerifyOnly` adds verification of an already prepared checkout.
- `PrepareBuildDependencies` now accepts `DependencyPreparationRequest` with
  repository and module directories.
- The private build receipt requires schema version 1 and module identity.
  Existing receipts must be regenerated before prebuilt delivery.
- Root-module committed-file checks exclude independent nested modules. Select
  those modules separately when their files need release validation.

The Go minimum remains 1.26.0. Root-module releases retain their existing note
path, unprefixed tags, profile defaults, and ordinary workflow without a module
map. The root orchestration facade and separate lightweight `buildinfo` facade
retain their roles; runtime version access requires no migration.

Source-tag publication remains the source-release completion point. Hosted page
and asset delivery remains asynchronous and can be retried from the same
immutable tag. ReleaseKit's deliverables remain its source tag and hosted note
page.

## Upgrade guidance

1. Select v0.4.0 in each consumer module that uses ReleaseKit. For API consumers:

   ```sh
   go get gitea.maximumdirect.net/eric/ReleaseKit@v0.4.0
   go mod tidy
   ```

   For consumers using the CLI as a Go tool dependency:

   ```sh
   go get -tool gitea.maximumdirect.net/eric/ReleaseKit/cmd/releasekit@v0.4.0
   go mod tidy
   ```

   Review and commit the resulting module and checksum changes together with
   caller, profile, and workflow updates. Keep historical tag retries paired
   with the tool and workflow recorded at that tag.

2. Update preparation API calls for `Tag` and `DependencyPreparationRequest`.
   For nested modules, set `ModuleDir` or profile `module_dir` to the physical
   module location, with its own `go.mod` declaration. Keep ordinary `Version`
   arguments as semantic versions. Use result `ModuleDir`, `ModulePath`, and
   `Tag` where module identity is needed. Product commands can distinguish their
   contexts through `RELEASEKIT_REPOSITORY_DIR` and `RELEASEKIT_MODULE_DIR`.

3. Update `ci-deliver` invocations to pass the full event tag and required
   `--commit OID`. Use `--prepared` after bootstrap verification and
   `--expected-module DIR` for mapped launchers. Prepare and commit each binary
   module's checksums before tagging so dependency preparation leaves tagged
   source clean. Root-only consumers can retain the ordinary tag workflow.

4. Rebuild existing prebuilt outputs with the v0.4.0 `build` command before
   `deliver --assets DIR`. Relative output and asset paths both resolve from the
   selected module. Review optional shared-file selections and nested-module
   validation coverage, then run the consumer's ordinary checks.

See the
[adoption guide](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.4.0/docs/consumers/adoption.md),
[configuration reference](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.4.0/docs/config.md),
[CLI contract](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.4.0/docs/cli.md),
[delivery guide](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.4.0/docs/consumers/delivery.md),
and [multi-module example](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.4.0/examples/multi-module/README.md)
for supported usage.

[COPYRIGHT](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.4.0/COPYRIGHT) |
[LICENSE](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.4.0/LICENSE) |
[ATTRIBUTION](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.4.0/docs/oss/attribution.md)