# ReleaseKit Adoption Roadmap **Last updated:** 2026-10-07 **Status:** Implementation complete; first adopting release and live delivery observation 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. The [implementation plan](implementation.md) owns the ordered execution steps and their verification; this roadmap owns the desired end state and adoption intent. 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.