Write release notes and migration guidance for v0.4.0

docs/releases/v0.4.0.md

@@ -0,0 +1,141 @@
+# 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)