diff --git a/docs/roadmap/releasekit.md b/docs/roadmap/releasekit.md new file mode 100644 index 0000000..70a821d --- /dev/null +++ b/docs/roadmap/releasekit.md @@ -0,0 +1,180 @@ +# ReleaseKit Adoption Roadmap + +**Last updated:** 2026-10-07 +**Status:** Adoption accepted; implementation pending. + +## Purpose and Baseline + +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. + +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. + +## 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. + +## Accepted Standardization Choices + +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. + +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. + +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. + +## Work Required + +### Dependency, Profile, and Tool Entry Point + +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. + +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. + +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. + +### Runtime Version Reporting + +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. + +### Publication and Binary Delivery + +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. + +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. + +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. + +### Tests and Removal of Duplicated Mechanics + +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. + +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. + +### Documentation and Attribution + +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. + +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. + +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. + +## Verification and Completion + +Adoption is complete when: + +- 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. + +Offline integration evidence and live delivery observations are distinct. +Observe the shared workflow during the first adopting release and address any +deployment failures through delivery recovery. CI success or asset availability +does not become a source-release completion gate. + +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; this roadmap +does not publish a release or prescribe implementation stages.