From 52e3a389bbb213da9796de4c60918dccfbecf37c Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Fri, 9 Oct 2026 03:17:16 +0000 Subject: [PATCH] Add release notes and upgrade guidance for v0.3.0 --- docs/releases/v0.3.0.md | 114 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 114 insertions(+) create mode 100644 docs/releases/v0.3.0.md diff --git a/docs/releases/v0.3.0.md b/docs/releases/v0.3.0.md new file mode 100644 index 0000000..871d7d0 --- /dev/null +++ b/docs/releases/v0.3.0.md @@ -0,0 +1,114 @@ +# ReleaseKit v0.3.0 + +## Summary + +ReleaseKit reduces repeated Git processes, validation memory retention, artifact +hashing, output copying, and runtime metadata parsing. It also improves +cancellation during validation shutdown and documents module-selected CLI +adoption and checksum recovery. + +## Changes + +- Committed-file checks share one lazy Git batch reader per validation operation. + Metadata-only checks start no content reader. Cancellation remains active + through reader shutdown, and cleanup reaps the child before validation returns. +- Validation releases regular-file source bytes after inspection and reuses + compact or parsed results by blob identity for Go formatting, module + replacements, Markdown documents, and symlink targets. Findings retain each + source path's locations and destination context. +- Managed and prebuilt delivery use one local asset verification pass before + hosted requests, removing the adjacent declaration-time hashing pass. Changed + assets still fail verification; exact remote comparisons, additive retries, + and partial-delivery reporting retain their behavior. +- Go commands transfer completed output buffers without an additional full + copy. Status-only successes release their captures, while failures retain + complete diagnostics and underlying causes. Capture remains in memory; + allocation costs depend on output size and write chunking. +- The runtime version accessor caches its build-metadata fallback safely across + calls. Linker-injected versions retain precedence, and the development fallback + remains unchanged. +- Shutdown errors are attributed to the last validation check that actually read + content. Selecting a later check with no applicable files preserves that + attribution, and an earlier check failure remains the primary error. +- CLI-only consumers have documented adoption through versioned Go tool + dependencies. The Woodpecker template supports both tool dependencies and + ordinary package dependencies selected by the tagged consumer module. +- Synthetic-module workflow tests use isolated module caches. New checksum + investigation guidance explains how to distinguish stale local metadata from + a download failure while preserving checksum verification and published tags. + +Performance gains depend on the consumer's workload. The changes preserve +complete in-memory diagnostics and existing validation selections. + +## Compatibility + +The declared minimum Go version remains 1.25.0, and module dependencies are +unchanged from v0.2.0. ReleaseKit's maintainer build toolchain and maintained +Woodpecker template images use Go 1.26.8; consumers select a local toolchain +compatible with their module and the selected ReleaseKit version. + +The root orchestration facade, separate lightweight `buildinfo` facade, public +signatures, CLI commands, and profile schema are unchanged. Existing v0.2.0 +callers and profiles require no source or configuration migration. + +Validation cleanup may now return the caller's cancellation cause where shutdown +previously remained blocked. Cleanup failures identify the check that used the +reader. Inspect structured validation errors with `errors.As` and underlying +causes with `errors.Is`. + +Source publication and hosted delivery retain their separate completion states. +ReleaseKit's deliverables remain the source tag and hosted Gitea note page. + +## Upgrade guidance + +1. Select v0.3.0 using the dependency form appropriate to the consumer. + + Go API consumers: + + ```sh + go get gitea.maximumdirect.net/eric/ReleaseKit@v0.3.0 + go mod tidy + ``` + + Consumers using ReleaseKit for repository release commands can register or + upgrade the CLI as a Go tool dependency: + + ```sh + go get -tool gitea.maximumdirect.net/eric/ReleaseKit/cmd/releasekit@v0.3.0 + go mod tidy + go tool releasekit version + ``` + + Review and commit the resulting module changes. API and tool dependencies + share the consumer's module graph and selected ReleaseKit version. + + A separately installed executable can be updated with: + + ```sh + go install gitea.maximumdirect.net/eric/ReleaseKit/cmd/releasekit@v0.3.0 + ``` + +2. Retain existing validation and delivery selections. The performance changes + apply automatically. Prepare dependencies before offline checks or builds, + and run the consumer's ordinary tests after upgrading. + +3. For module-selected Woodpecker delivery, commit the dependency upgrade before + tagging the consumer. Choose a compatible local Go image; delivery and retries + continue to use the triggering tag's module selection. CLI-only consumers can + use the tool declaration to retain ReleaseKit through `go mod tidy`. + +4. If dependency preparation reports a checksum mismatch, follow the + [checksum investigation guide](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.3.0/docs/consumers/delivery.md#investigating-module-checksum-mismatches). + Repair a confirmed stale cache entry while retaining checksum verification + and the application's recorded checksums. + +See the +[adoption guide](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.3.0/docs/consumers/adoption.md), +[candidate check guide](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.3.0/docs/consumers/check.md), +[delivery guide](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.3.0/docs/consumers/delivery.md), +and [runtime version guide](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.3.0/docs/consumers/runtime-version.md) +for supported behavior and usage. + +[COPYRIGHT](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.3.0/COPYRIGHT) | +[LICENSE](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.3.0/LICENSE) | +[ATTRIBUTION](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.3.0/docs/oss/attribution.md)