audita/docs/roadmap/releasekit.md

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: 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 <version> 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 <version> 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-<version>-linux-amd64, audita-<version>-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 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.