232 lines
13 KiB
Markdown
232 lines
13 KiB
Markdown
# ReleaseKit v0.3.0 Upgrade Roadmap
|
|
|
|
**Last updated:** 2026-10-08
|
|
**Status:** Implementation complete; first upgraded release and live delivery
|
|
observation pending.
|
|
|
|
## Purpose
|
|
|
|
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.
|
|
|
|
This roadmap replaces the completed initial-adoption roadmap. It records the
|
|
upgrade's target state and completed scope. The upgrade was implemented in one
|
|
pass without a separate staged plan.
|
|
|
|
## Current Baseline
|
|
|
|
At Audita commit `17421bc5f352f3fdeb67561b2b60b49979822228`:
|
|
|
|
- `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.
|
|
|
|
Since that baseline, Audita has adopted release policy 1.6, registered and
|
|
upgraded the ReleaseKit tool to v0.3.0, simplified the local wrapper, and
|
|
updated CI and notices. The current Go minimum is 1.26.0; the selected release
|
|
toolchain is 1.26.8. The scope below records the requirements fulfilled by this
|
|
implementation.
|
|
|
|
## 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.
|
|
|
|
The adopted release policy uses 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
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
## Implemented Scope
|
|
|
|
### Module Selection and Local Tooling
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
### Toolchain and CI
|
|
|
|
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`.
|
|
|
|
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.
|
|
|
|
### Policy Alignment and Documentation
|
|
|
|
The release-policy update is complete. `docs/policy/release.md` now incorporates
|
|
the selected upstream 1.6 revision, with template-only instructions removed and
|
|
Audita's platform commitments and accepted native-host version check retained.
|
|
It preserves independent source completion and proportionate automated gates.
|
|
Mixed-revision attribution records the policy's exact source separately from
|
|
the other adopted policies. No human release gate was introduced.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
### Attribution
|
|
|
|
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.
|
|
|
|
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. The copied release policy's scope and
|
|
commit-specific source and notice links have already been updated; preserve
|
|
that accurate mixed-revision attribution during the remaining upgrade work.
|
|
|
|
### Consumer Verification and Test Maintenance
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
## Scope Boundaries
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
## Acceptance and Existing Evidence
|
|
|
|
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 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.
|
|
|
|
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.
|
|
|
|
## Implementation Completion
|
|
|
|
Completed with Go 1.26.8. The readonly offline full suite passed. The real local
|
|
wrapper selected ReleaseKit v0.3.0; disposable Go-tool fixtures verified native
|
|
argument boundaries, statuses 0/2/3, and unchanged module files. The CI workflow
|
|
matches the v0.3.0 maintained template with Audita's existing secret mapping.
|
|
The real ReleaseKit builder produced both required Linux artifacts using the
|
|
test identifier v0.0.0, passed its native version smoke check, and emitted
|
|
matching artifact digests in its build receipt. Temporary output was removed.
|
|
The new release-tool dependencies are absent from Audita's runtime dependency
|
|
list. ReleaseKit and Go runtime/vendor attribution identify their selected
|
|
source revisions, with existing applicable license texts reused.
|
|
|
|
This verification built modified local source and did not claim a clean,
|
|
published release candidate. Release preparation will validate its final
|
|
committed candidate through the ordinary publication command. No tags, source
|
|
pushes, hosted uploads, or LLM calls were made during implementation; live
|
|
artifact delivery remains a separate observation for the next release.
|