From 36823c91fbd558361c2a21a80b87fc794de335b8 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Fri, 9 Oct 2026 03:44:10 +0000 Subject: [PATCH] Plan the ReleaseKit v0.3.0 upgrade --- docs/roadmap/releasekit.md | 342 ++++++++++++++++++------------------- 1 file changed, 167 insertions(+), 175 deletions(-) diff --git a/docs/roadmap/releasekit.md b/docs/roadmap/releasekit.md index 74c699a..16badef 100644 --- a/docs/roadmap/releasekit.md +++ b/docs/roadmap/releasekit.md @@ -1,216 +1,208 @@ -# ReleaseKit Adoption Roadmap +# ReleaseKit v0.3.0 Upgrade Roadmap -**Last updated:** 2026-10-07 -**Status:** Implementation complete; first adopting release and live delivery -observation pending. +**Last updated:** 2026-10-08 +**Status:** Agreed scope; implementation pending. -## Purpose and Original Baseline +## Purpose -Implement the decision in [ADR 0001](../adr/0001-releasekit.md): standardize -Audita's release process on ReleaseKit to improve maintainability and reduce -locally owned release-focused code. Those benefits outweigh the small advantages -of retaining Audita's custom procedure. The workflow changes required by the -shared standard are accepted. +Upgrade Audita directly from ReleaseKit v0.1.0 to v0.3.0, continuing the decision +in [ADR 0001](../adr/0001-releasekit.md). Shared release mechanics belong in +ReleaseKit; Audita supplies product facts, compatibility decisions, release +notes, and thin integration wiring. Standardization and less locally owned +release code remain the reasons for adoption. -At Audita revision `6de470b53d185b10327ec4deba23f5a84e606e1f`, v3.0.0 is -released. Audita owns `scripts/release.sh`, `scripts/build-release.sh`, and -`scripts/release_test.go`, totaling 207 lines, plus the 26-line Woodpecker delivery -workflow. Publication validates a clean candidate, cross-builds Linux binaries, -and atomically pushes `main` and a lightweight tag. Woodpecker builds artifacts -and uses a release plugin to publish the note, binaries, and checksums. Audita -has no runtime version command. - -The adoption baseline is ReleaseKit v0.1.0, commit -`5e60fe3113c69f95c42fbbe32a8ca4b51f5b83c1`. Its public library, executable, -`buildinfo` package, and maintained Woodpecker integration cover the required -mechanics. The upstream test suite passes; its documentation records live -Woodpecker/Gitea verification as remaining deployment work. +This roadmap replaces the completed initial-adoption roadmap. It defines the +upgrade's target state and required work; a later implementation plan can own +ordered execution steps. ## Current Baseline -The adoption implementation is now present: `go.mod` selects ReleaseKit -v0.1.0, `releasekit.json` supplies Audita's product and delivery facts, -`scripts/release.sh` builds and forwards arguments to its executable, and -`.woodpecker/release.yml` invokes the same pinned version for tag delivery. -The application exposes `audita version` through `buildinfo`; the custom -release builder has been removed. The sections below retain the intended -adoption scope rather than describing work that still needs implementation. +At Audita commit `17421bc5f352f3fdeb67561b2b60b49979822228`: -The [adoption review](remediation.md) records focused CLI and wiring-test -findings and their resolution status. Remaining implementation corrections -belong there. First-release delivery observation remains deployment work, -separate from source-release completion. +- `go.mod` selects ReleaseKit v0.1.0 and declares Go 1.25.5. Audita imports the + lightweight `buildinfo` facade for its configuration-free version command. + The ReleaseKit CLI is not registered as a Go tool dependency. +- `scripts/release.sh` builds the module-selected CLI using temporary copies of + module metadata, then forwards native arguments and exit status. +- `.woodpecker/release.yml` already verifies the event tag and commit before + bootstrapping the tool from that tag's module selection. Its Go image is + `golang:1.25.5`; the delivery secret remains `GITEA_RELEASE_TOKEN`. +- `releasekit.json` selects Linux amd64 and arm64 artifacts and Audita's Gitea + destination. It enables no optional validation checks or additional commands. +- The release procedure uses main-first publication, annotated tags, offline + candidate tests, selected builds, and the native version smoke check. Source + publication completes independently of CI and artifact delivery. +- The local release policy is based on Standard Repository Policies version 1.4. + It lacks the newer distinction between the consumer minimum and release + toolchain and the explicit minor-release exception for Go-minimum increases. +- Release tests include exact expectations for the current dependency version + and Go image. Documentation and attribution still identify the old versions. + +The initial adoption's [review findings](remediation.md) are resolved. They are +historical context, not additional work for this upgrade. + +## Selected Upstream Revisions + +Adopt ReleaseKit **v0.3.0**, commit +`e43df4416e0ed987349b2ea04a2c68c25e552772`. +Its [release note](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.3.0/docs/releases/v0.3.0.md) +records reduced Git subprocess work, source retention, artifact hashing, and +output copying, plus improved cancellation and isolated synthetic-module test +caches. Public signatures, CLI commands, and profiles remain compatible with +v0.2.0. The required Go minimum is now 1.26.0. + +The direct upgrade also includes v0.2.0's optional declarative validation and +structured diagnostics. Audita already uses its module-selected CI bootstrap +approach. The largest file-validation performance gains apply only when those +checks are selected; this upgrade does not enable them merely to obtain gains. + +For the release-policy update, use Standard Repository Policies **version 1.6** +at commit `e833faddf120c789a9b45348edaf75720de16348`, following its +[adoption guide](https://gitea.maximumdirect.net/eric/policy/src/commit/e833faddf120c789a9b45348edaf75720de16348/docs/adoption.md). +Other locally adopted policies retain their existing upstream revisions. ## Target End State -- ReleaseKit owns candidate validation, source publication, version injection, - selected-target builds, checksum generation, and hosted delivery. Audita owns - its product facts, compatibility decisions, release notes, and necessary - product-specific checks. -- A small `releasekit.json` declares product `Audita`, remote `origin`, main - package `./cmd/audita`, binary name `audita`, and delivery targets - `linux/amd64` and `linux/arm64`. Its Gitea destination identifies - `https://gitea.maximumdirect.net`, owner `eric`, and repository `audita`. -- Maintainers commit the candidate and publish it to authoritative `main` - before invoking ReleaseKit publication. ReleaseKit validates that candidate, - creates an annotated tag from the committed note, and pushes its exact tag - object. Confirmed source publication completes the release independently of - CI and artifact delivery. -- One captured candidate receives ReleaseKit's standard offline test suite and - selected build verification. Audita's profile introduces no additional checks - without a concrete product need. The optional local check remains a diagnostic - operation rather than a prerequisite that duplicates publication validation. -- `audita version` reports `audita ` through ReleaseKit's public - `buildinfo.Version()` accessor. Ordinary development builds use its native - fallback behavior, including `dev` when release information is unavailable. -- Woodpecker invokes the pinned shared `ci-deliver` command. Hosted notes, - Linux assets, and `SHA256SUMS` retain their current identities; delivery - compares existing content, adds missing assets, and reports conflicts and - uncertainty separately from source publication. -- Audita's release code consists of thin tool invocation and product wiring, - with focused integration coverage. Common mechanics and their repeated tests - reside upstream. +Audita selects ReleaseKit v0.3.0 for both `buildinfo` and the registered CLI +through one module graph. The application continues to expose the existing +version command without configuration or LLM setup. Release orchestration and +its dependencies stay outside transcript processing. -## Accepted Standardization Choices +The consumer/source-build minimum is **Go 1.26.0**. The selected maintainer and +CI release-build toolchain is **Go 1.26.8**. The patch used for validation and +builds is separate from the minimum supported for source consumers. Running a +distributed Audita executable does not require installing Go. -Adopt ReleaseKit's main-first publication and annotated tags, replacing the -atomic branch/tag push and lightweight tags for new releases. Existing released -tags, notes, pages, and assets retain their historical contents. +Local tooling uses the module-selected Go tool with only the repository +selection and native invocation wiring needed by Audita. CI continues to select +ReleaseKit from the triggering tag's module files, preserving the existing +secret mapping and protection of tagged source during bootstrap. Historical +tag retries retain their own dependency selections. -Adopt its standard build settings and mandatory native version smoke check. -The check verifies that version injection reaches the executable. On a host -outside the selected Linux targets, ReleaseKit can build a temporary native -binary; publication from that host depends on that check succeeding. This is an -accepted workflow change, including for macOS invocations. Linux remains the -production delivery target, and macOS remains a best-effort development platform. -Mac access and macOS artifact delivery are not release prerequisites. +The profile, production targets, artifact identities, version semantics, and +source-completion rule retain their current behavior. Linux amd64 and arm64 +remain required; macOS arm64 remains best effort. ReleaseKit continues to own +candidate validation, publication, builds, checksums, and delivery recovery. -Use the shared managed build-and-deliver operation for ordinary CI delivery. -ReleaseKit's retained-artifact workflow remains available when a delivery retry -needs the original bytes. Follow its content-aware recovery behavior rather -than reproducing that machinery in Audita. +The local release policy adopts upstream's explicit allowance for Go-minimum +increases in minor releases, with the increase and required source-consumer +action explained in the release note. Patch releases preserve the consumer +minimum. Other compatibility changes remain governed by the adopted policy. -## Adoption Scope +## Work Required -### Dependency, Profile, and Tool Entry Point +### Module Selection and Local Tooling -Select the released v0.1.0 module in `go.mod` and `go.sum`. The application uses -the lightweight `buildinfo` facade; release orchestration is exercised through -the upstream executable. The sibling checkout is review material, not a -production dependency replacement. +Upgrade the released dependency directly to v0.3.0 and register +`gitea.maximumdirect.net/eric/ReleaseKit/cmd/releasekit` in Go's `tool` metadata. +Run module tidying and review the resulting `go.mod` and `go.sum`. The tool +registration retains CLI-only dependencies and their checksums through tidying; +no local checkout replacement is needed. -Add the product profile described above. Leave additional checks empty and keep -delivery tokens out of the profile. Use `RELEASEKIT_GITEA_TOKEN` as the token -environment variable, supplied from the existing Woodpecker -`GITEA_RELEASE_TOKEN` secret. +Simplify `scripts/release.sh` around the selected tool. Remove its temporary +module-file bootstrap where the registered tool and prepared dependencies make +that machinery unnecessary. Preserve argument boundaries, native status +forwarding, and the separation between tool preparation and offline candidate +validation. Keep the existing documented entry point proportionately covered. -Reduce `scripts/release.sh` to repository selection, building the CLI selected -by Audita's module graph into ignored `bin/` output, and invoking it directly. -Forward ReleaseKit's native commands and arguments and preserve its exit status, -including uncertain publication status. Use the same released tool version in -the module graph and CI pin. Dependency/tool preparation belongs before offline -candidate validation. +### Toolchain and CI -### Runtime Version Reporting +Declare Go 1.26.0 in `go.mod` and use Go 1.26.8 for maintainer release tooling, +candidate validation, and CI artifact builds. Update the Woodpecker image to a +compatible Go 1.26.8 image with Git. Keep local toolchain selection explicit; +Go 1.25.5 cannot build this dependency with `GOTOOLCHAIN=local`. -Add `version` to the existing CLI dispatch and help, with output -`audita ` followed by a newline and exit status zero. This operation -works without loading application configuration, resolving LLM credentials, or -contacting a provider. Use the public accessor and let ReleaseKit own injection -mechanics. Keep the release orchestration dependency outside transcript -processing. +Align CI with the maintained v0.3.0 tag-delivery integration while retaining +Audita's destination, secret mapping, and module-based tool selection. Preserve +tag verification before Go bootstrap and temporary metadata outside the tagged +checkout where the upstream CI template uses it. The local and CI integrations +need not have identical preparation machinery when their responsibilities differ. -### Publication and Binary Delivery +### Release Policy and Documentation -Replace the local publication and cross-build mechanics with ReleaseKit's -commands and profile. Retire `scripts/build-release.sh` when its callers use -the shared builder. +Update `docs/policy/release.md` using the selected upstream 1.6 revision. Adopt +upstream wording for shared requirements, remove template-only instructions, +and retain Audita's justified platform commitments and accepted native-host +version check. Preserve main-first publication, independent source completion, +and proportionate automated gates. No human release gate is introduced. -Replace the current Woodpecker build/plugin sequence with the maintained -tag-delivery integration, pinned to v0.1.0. Retain a compatible Go 1.25.5 image -with Git, the existing secret, and only the selected Linux targets. Pass the -workspace, event commit, and version to `ci-deliver`; the shared command owns -tagged-checkout verification, dependency preparation, build, and delivery. +Record the adopted version, local update date, and exact per-document upstream +source. Keep mixed-revision policy attribution accurate rather than implying +that the whole policy suite was refreshed. Existing public discovery links and +unrelated policy adoption metadata remain applicable. -The declared artifacts remain `audita--linux-amd64`, -`audita--linux-arm64`, and `SHA256SUMS`. The committed release note -supplies the hosted body and required licensing footer. Delivery status and -recovery follow the upstream operation; source publication does not poll CI or -wait for assets. +Update `docs/release.md` and `docs/development.md` for the source minimum, +selected release toolchain, dependency preparation, and simplified local +invocation. Refresh relevant upstream links to v0.3.0. Update other canonical +references only where the implementation changes their facts. The accepted ADR +continues to apply and its decision content needs no revision. -### Tests and Removal of Duplicated Mechanics +When preparing the next release, explain the Go-minimum increase and maintainer +workflow changes in its new note. Version selection and publication timing +remain release-preparation tasks. Preserve existing tagged notes and assets. -Replace the repeated release-mechanics matrix in `scripts/release_test.go` -with proportionate coverage of Audita's wiring. Protect the new version command -and wrapper/profile integration where these introduce distinct consumer risks. -Verify actual version injection and the selected Linux builds through the real -builder during adoption validation. Use local Git/HTTP fixtures and controlled -command boundaries where needed; keep the default suite offline. +### Attribution -Reuse ReleaseKit's coverage for common Git guards, push reconciliation, -checksums, and delivery retries. Evaluate the reduction in local machinery from -the resulting implementation rather than imposing a numerical deletion target. +Update ReleaseKit's entry in `docs/oss/attribution.md` to the selected version +and exact source commit. Its LGPL-3.0-or-later grant remains unchanged. Review +CLI-only dependencies according to their actual use and distribution; a module +requirement alone does not establish incorporation into Audita binaries. -### Documentation and Attribution +Update Go runtime and standard-library notices, including relevant vendored +components, for the selected Go 1.26.8 release-build toolchain. Reuse existing +license texts where applicable. Update the copied release policy's scope and +commit-specific source and notice links under the existing OSS policy. -Update `docs/release.md` for main-first preparation, native ReleaseKit commands, -annotated tags, dependency preparation, delivery status, and failure recovery. -Align `docs/policy/release.md` where necessary to describe the deliberately -accepted native-host check while retaining the existing production targets and -independent source-completion rule. +### Consumer Verification and Test Maintenance -Update `docs/cli.md`, relevant internal CLI guidance, and the ADR index for the -version command and accepted decision. Keep the ADR's decision content intact. -Record the adoption and maintainer workflow change in the next release note -when that release is prepared. +Update release integration coverage for the new selection, tool declaration, +CI image, and simplified wrapper. Remove assertions that elevate a particular +dependency version, image spelling, or bootstrap implementation into a lasting +prohibition on legitimate upgrades. Older-version fixtures can remain when they +protect tagged-version selection; do not replace every historical value. -Add ReleaseKit's selected source and LGPL-3.0-or-later notices to -`docs/oss/attribution.md` under the existing OSS policy. Reuse applicable license -texts already present. Incorporating `buildinfo` does not change Audita's -application license. +Retain proportionate protection of product facts, target membership, native +argument/status forwarding, preparation failures, and tagged-source selection. +Rely on upstream coverage for common release mechanics. Tests using synthetic +module downloads must use test-owned module caches. -## Verification and Completion +Run the ordinary offline suite and verify both Linux builds with the selected +toolchain. Exercise the real ReleaseKit build/version-injection path as an +upgrade check. These checks do not require source publication, hosted uploads, +real delivery credentials, or LLM calls. -Adoption is complete when: +## Scope Boundaries -- The released dependency and pinned tool are selected consistently, and the - application builds with its default offline test suite passing. -- Version output works without LLM setup and reports the injected version from - a ReleaseKit-built executable. -- The native profile and thin wrapper drive candidate checks and publication - without Audita retaining common publication or build mechanics. -- Both required Linux targets build through ReleaseKit, and the CI workflow - declares the intended destination, artifacts, note body, and secret mapping. -- Focused consumer coverage exercises the changed boundaries, and redundant - mechanics tests and the old builder have been retired. -- Current documentation and attribution describe the adopted behavior. +This is a dependency, tooling, and release-policy upgrade. Transcript processing, +application configuration, LLM behavior, and output formats retain their current +contracts. Keep optional validation and additional checks at their current +selections. Adding race, vet, formatting, Markdown, distribution, file-size, or +new publication-destination checks is a separate deliberate choice. -## Remaining Release and Deployment Work +No intermediate v0.2.0 adoption, compatibility scaffolding, patch-version test +matrix, performance threshold, or quantified code-deletion target is required. +Use the implementation's resulting simplicity to assess reduced ownership. +CI success and downloadable artifacts remain separate delivery observations, +not source-release completion gates. -Prepare the first adopting release under the [release procedure](../release.md), -including a release note explaining the maintainer workflow change. Resolve -outstanding adoption-review findings through the linked remediation record. -Version selection and publication timing remain release-preparation decisions. +## Acceptance and Existing Evidence -Offline integration evidence and live delivery observations are distinct. -Observe the shared workflow during the first adopting release and address any -deployment failures through ReleaseKit's delivery recovery. Check that the -tagged commit, hosted note with its licensing footer, selected Linux assets, -and checksums reach the intended destination. This observation is asynchronous; -CI success or asset availability does not become a source-release completion -gate or require the publication command to wait. +The upgrade is complete when the selected dependency and tool declaration are +consistent; the module minimum and release-build toolchain are recorded in their +canonical owners; the local wrapper and tagged CI integration use that selection; +and the ordinary tests and required Linux builds pass. Version injection must +still reach Audita's existing version command. Policy provenance, attribution, +and current documentation must describe the implemented upgrade accurately. -The accepted ADR settles the architectural choice and standard workflow -trade-offs. No significant feature decisions remain open. The next Audita -version and publication timing belong to release preparation. The -[implementation plan](implementation.md) owns the ordered execution steps and -their verification; this roadmap owns the desired end state and adoption intent. +The preceding review already passed ReleaseKit's full suite and a disposable +Audita upgrade's full suite on Go 1.26.8, after adjusting the current-version +assertion in that copy. Linux amd64 and arm64 compilation succeeded, and the +new tool dependencies were absent from Audita's runtime dependency list. That +evidence supports feasibility; it does not substitute for verifying the final +implementation, simplified bootstrap, or real injected-version build. -Implementation completed 2026-10-07 at revision -`5ac704c4c42fd23ed94b1f7351491ad580726db1`. The full Go suite and executable -version path passed, and ReleaseKit built both selected Linux artifacts with -its native version smoke check passing. The profile, dependency and CI pins, -wrapper, and parsed workflow were verified together. Audita's local release -builder and publication mechanics are retired. This completion record is a -later documentation-only commit; live delivery remains to be observed during -the first adopting release and is separate from source implementation. +Live Woodpecker/Gitea delivery was not exercised during review. Observe delivery +asynchronously when the first upgraded release is published and address any +deployment failures through the shared recovery procedure. No significant +feature decisions remain open; implementation details and final release +preparation can be resolved within the agreed scope.