192 lines
10 KiB
Markdown
192 lines
10 KiB
Markdown
# 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 <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](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.
|