From 5a0bc6f78b7daded05adf340ab394baa358ef6e4 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sat, 10 Oct 2026 15:39:47 +0000 Subject: [PATCH] Write release notes and migration guidance for v0.4.0 --- docs/releases/v0.4.0.md | 141 +++++++++++++++++++++++++++++ docs/roadmap/implementation.md | 8 +- docs/roadmap/next-release-notes.md | 119 ------------------------ 3 files changed, 146 insertions(+), 122 deletions(-) create mode 100644 docs/releases/v0.4.0.md delete mode 100644 docs/roadmap/next-release-notes.md diff --git a/docs/releases/v0.4.0.md b/docs/releases/v0.4.0.md new file mode 100644 index 0000000..b948c77 --- /dev/null +++ b/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) diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 53fa0a8..91a4bf7 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -733,8 +733,8 @@ evidence describe the complete implemented feature. owners. Explain module selection, semantic version versus full tag, declared versus physical module identity, note/source/license links, path bases, boundaries, shared-file semantics, preparation, and receipt ownership. -2. Write `docs/roadmap/next-release-notes.md` as the next release's pending notes - and migration guidance. A release version is not selected by this feature; +2. Write the next release's pending notes and migration guidance. + A release version is not selected by this feature; keep the draft under roadmap ownership until release preparation assigns its `docs/releases/.md` destination. Include API/profile updates, the preparation signature and tag field changes, receipt regeneration, CI mapping @@ -764,7 +764,9 @@ implemented examples and canonical documentation agree with the current API. Gitea and internal ownership documents, recovery guidance, and maintained examples for module selection, full tags, path bases, shared files, preparation, and receipt ownership. Added pending next-release notes with migration guidance -and corrected the current Go minimum facts. Audited acceptance coverage against +and corrected the current Go minimum facts. Release preparation promoted those +notes to [the v0.4.0 release note](../releases/v0.4.0.md). +Audited acceptance coverage against the stage-owned tests and reviewed ReleaseKit's root release procedure against the adopted release policy; no new release gates were added. Verified `go test ./...`, `go run ./internal/apicheck`, local links and heading fragments diff --git a/docs/roadmap/next-release-notes.md b/docs/roadmap/next-release-notes.md deleted file mode 100644 index cd3e618..0000000 --- a/docs/roadmap/next-release-notes.md +++ /dev/null @@ -1,119 +0,0 @@ -# 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/.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. - -Select this feature's ReleaseKit release in each consumer module before adopting -the new profiles and workflows. Upgrade its tool declaration and workflow -together: pre-feature tools through v0.3.0 require their historical profiles and -flags. Historical tag retries use the workflow matching the tool recorded at -that tag. Preserve the immutable -tag and module files when retrying. - -- 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). - -## Release preparation - -Once this release's version is selected, record it in the maintained multi-module -example's tool and require directives, and move these notes to its release-note -path. Example setup currently selects a compatible version explicitly; disposable -fixtures can verify current source before publication. Synthetic dependency -versions belong to generated test metadata and local fixture proxies.