Plan the ReleaseKit v0.3.0 upgrade
This commit is contained in:
@@ -1,216 +1,208 @@
|
|||||||
# ReleaseKit Adoption Roadmap
|
# ReleaseKit v0.3.0 Upgrade Roadmap
|
||||||
|
|
||||||
**Last updated:** 2026-10-07
|
**Last updated:** 2026-10-08
|
||||||
**Status:** Implementation complete; first adopting release and live delivery
|
**Status:** Agreed scope; implementation pending.
|
||||||
observation pending.
|
|
||||||
|
|
||||||
## Purpose and Original Baseline
|
## Purpose
|
||||||
|
|
||||||
Implement the decision in [ADR 0001](../adr/0001-releasekit.md): standardize
|
Upgrade Audita directly from ReleaseKit v0.1.0 to v0.3.0, continuing the decision
|
||||||
Audita's release process on ReleaseKit to improve maintainability and reduce
|
in [ADR 0001](../adr/0001-releasekit.md). Shared release mechanics belong in
|
||||||
locally owned release-focused code. Those benefits outweigh the small advantages
|
ReleaseKit; Audita supplies product facts, compatibility decisions, release
|
||||||
of retaining Audita's custom procedure. The workflow changes required by the
|
notes, and thin integration wiring. Standardization and less locally owned
|
||||||
shared standard are accepted.
|
release code remain the reasons for adoption.
|
||||||
|
|
||||||
At Audita revision `6de470b53d185b10327ec4deba23f5a84e606e1f`, v3.0.0 is
|
This roadmap replaces the completed initial-adoption roadmap. It defines the
|
||||||
released. Audita owns `scripts/release.sh`, `scripts/build-release.sh`, and
|
upgrade's target state and required work; a later implementation plan can own
|
||||||
`scripts/release_test.go`, totaling 207 lines, plus the 26-line Woodpecker delivery
|
ordered execution steps.
|
||||||
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.
|
|
||||||
|
|
||||||
## Current Baseline
|
## Current Baseline
|
||||||
|
|
||||||
The adoption implementation is now present: `go.mod` selects ReleaseKit
|
At Audita commit `17421bc5f352f3fdeb67561b2b60b49979822228`:
|
||||||
v0.1.0, `releasekit.json` supplies Audita's product and delivery facts,
|
|
||||||
`scripts/release.sh` builds and forwards arguments to its executable, and
|
|
||||||
`.woodpecker/release.yml` invokes the same pinned version for tag delivery.
|
|
||||||
The application exposes `audita version` through `buildinfo`; the custom
|
|
||||||
release builder has been removed. The sections below retain the intended
|
|
||||||
adoption scope rather than describing work that still needs implementation.
|
|
||||||
|
|
||||||
The [adoption review](remediation.md) records focused CLI and wiring-test
|
- `go.mod` selects ReleaseKit v0.1.0 and declares Go 1.25.5. Audita imports the
|
||||||
findings and their resolution status. Remaining implementation corrections
|
lightweight `buildinfo` facade for its configuration-free version command.
|
||||||
belong there. First-release delivery observation remains deployment work,
|
The ReleaseKit CLI is not registered as a Go tool dependency.
|
||||||
separate from source-release completion.
|
- `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.
|
||||||
|
|
||||||
|
## 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.
|
||||||
|
|
||||||
|
For the release-policy update, use 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
|
## Target End State
|
||||||
|
|
||||||
- ReleaseKit owns candidate validation, source publication, version injection,
|
Audita selects ReleaseKit v0.3.0 for both `buildinfo` and the registered CLI
|
||||||
selected-target builds, checksum generation, and hosted delivery. Audita owns
|
through one module graph. The application continues to expose the existing
|
||||||
its product facts, compatibility decisions, release notes, and necessary
|
version command without configuration or LLM setup. Release orchestration and
|
||||||
product-specific checks.
|
its dependencies stay outside transcript processing.
|
||||||
- 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
|
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.
|
||||||
|
|
||||||
Adopt ReleaseKit's main-first publication and annotated tags, replacing the
|
Local tooling uses the module-selected Go tool with only the repository
|
||||||
atomic branch/tag push and lightweight tags for new releases. Existing released
|
selection and native invocation wiring needed by Audita. CI continues to select
|
||||||
tags, notes, pages, and assets retain their historical contents.
|
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.
|
||||||
|
|
||||||
Adopt its standard build settings and mandatory native version smoke check.
|
The profile, production targets, artifact identities, version semantics, and
|
||||||
The check verifies that version injection reaches the executable. On a host
|
source-completion rule retain their current behavior. Linux amd64 and arm64
|
||||||
outside the selected Linux targets, ReleaseKit can build a temporary native
|
remain required; macOS arm64 remains best effort. ReleaseKit continues to own
|
||||||
binary; publication from that host depends on that check succeeding. This is an
|
candidate validation, publication, builds, checksums, and delivery recovery.
|
||||||
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.
|
The local release policy adopts upstream's explicit allowance for Go-minimum
|
||||||
ReleaseKit's retained-artifact workflow remains available when a delivery retry
|
increases in minor releases, with the increase and required source-consumer
|
||||||
needs the original bytes. Follow its content-aware recovery behavior rather
|
action explained in the release note. Patch releases preserve the consumer
|
||||||
than reproducing that machinery in Audita.
|
minimum. Other compatibility changes remain governed by the adopted policy.
|
||||||
|
|
||||||
## Adoption Scope
|
## Work Required
|
||||||
|
|
||||||
### Dependency, Profile, and Tool Entry Point
|
### Module Selection and Local Tooling
|
||||||
|
|
||||||
Select the released v0.1.0 module in `go.mod` and `go.sum`. The application uses
|
Upgrade the released dependency directly to v0.3.0 and register
|
||||||
the lightweight `buildinfo` facade; release orchestration is exercised through
|
`gitea.maximumdirect.net/eric/ReleaseKit/cmd/releasekit` in Go's `tool` metadata.
|
||||||
the upstream executable. The sibling checkout is review material, not a
|
Run module tidying and review the resulting `go.mod` and `go.sum`. The tool
|
||||||
production dependency replacement.
|
registration retains CLI-only dependencies and their checksums through tidying;
|
||||||
|
no local checkout replacement is needed.
|
||||||
|
|
||||||
Add the product profile described above. Leave additional checks empty and keep
|
Simplify `scripts/release.sh` around the selected tool. Remove its temporary
|
||||||
delivery tokens out of the profile. Use `RELEASEKIT_GITEA_TOKEN` as the token
|
module-file bootstrap where the registered tool and prepared dependencies make
|
||||||
environment variable, supplied from the existing Woodpecker
|
that machinery unnecessary. Preserve argument boundaries, native status
|
||||||
`GITEA_RELEASE_TOKEN` secret.
|
forwarding, and the separation between tool preparation and offline candidate
|
||||||
|
validation. Keep the existing documented entry point proportionately covered.
|
||||||
|
|
||||||
Reduce `scripts/release.sh` to repository selection, building the CLI selected
|
### Toolchain and CI
|
||||||
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
|
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`.
|
||||||
|
|
||||||
Add `version` to the existing CLI dispatch and help, with output
|
Align CI with the maintained v0.3.0 tag-delivery integration while retaining
|
||||||
`audita <version>` followed by a newline and exit status zero. This operation
|
Audita's destination, secret mapping, and module-based tool selection. Preserve
|
||||||
works without loading application configuration, resolving LLM credentials, or
|
tag verification before Go bootstrap and temporary metadata outside the tagged
|
||||||
contacting a provider. Use the public accessor and let ReleaseKit own injection
|
checkout where the upstream CI template uses it. The local and CI integrations
|
||||||
mechanics. Keep the release orchestration dependency outside transcript
|
need not have identical preparation machinery when their responsibilities differ.
|
||||||
processing.
|
|
||||||
|
|
||||||
### Publication and Binary Delivery
|
### Release Policy and Documentation
|
||||||
|
|
||||||
Replace the local publication and cross-build mechanics with ReleaseKit's
|
Update `docs/policy/release.md` using the selected upstream 1.6 revision. Adopt
|
||||||
commands and profile. Retire `scripts/build-release.sh` when its callers use
|
upstream wording for shared requirements, remove template-only instructions,
|
||||||
the shared builder.
|
and retain Audita's justified platform commitments and accepted native-host
|
||||||
|
version check. Preserve main-first publication, independent source completion,
|
||||||
|
and proportionate automated gates. No human release gate is introduced.
|
||||||
|
|
||||||
Replace the current Woodpecker build/plugin sequence with the maintained
|
Record the adopted version, local update date, and exact per-document upstream
|
||||||
tag-delivery integration, pinned to v0.1.0. Retain a compatible Go 1.25.5 image
|
source. Keep mixed-revision policy attribution accurate rather than implying
|
||||||
with Git, the existing secret, and only the selected Linux targets. Pass the
|
that the whole policy suite was refreshed. Existing public discovery links and
|
||||||
workspace, event commit, and version to `ci-deliver`; the shared command owns
|
unrelated policy adoption metadata remain applicable.
|
||||||
tagged-checkout verification, dependency preparation, build, and delivery.
|
|
||||||
|
|
||||||
The declared artifacts remain `audita-<version>-linux-amd64`,
|
Update `docs/release.md` and `docs/development.md` for the source minimum,
|
||||||
`audita-<version>-linux-arm64`, and `SHA256SUMS`. The committed release note
|
selected release toolchain, dependency preparation, and simplified local
|
||||||
supplies the hosted body and required licensing footer. Delivery status and
|
invocation. Refresh relevant upstream links to v0.3.0. Update other canonical
|
||||||
recovery follow the upstream operation; source publication does not poll CI or
|
references only where the implementation changes their facts. The accepted ADR
|
||||||
wait for assets.
|
continues to apply and its decision content needs no revision.
|
||||||
|
|
||||||
### Tests and Removal of Duplicated Mechanics
|
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.
|
||||||
|
|
||||||
Replace the repeated release-mechanics matrix in `scripts/release_test.go`
|
### Attribution
|
||||||
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,
|
Update ReleaseKit's entry in `docs/oss/attribution.md` to the selected version
|
||||||
checksums, and delivery retries. Evaluate the reduction in local machinery from
|
and exact source commit. Its LGPL-3.0-or-later grant remains unchanged. Review
|
||||||
the resulting implementation rather than imposing a numerical deletion target.
|
CLI-only dependencies according to their actual use and distribution; a module
|
||||||
|
requirement alone does not establish incorporation into Audita binaries.
|
||||||
|
|
||||||
### Documentation and Attribution
|
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. Update the copied release policy's scope and
|
||||||
|
commit-specific source and notice links under the existing OSS policy.
|
||||||
|
|
||||||
Update `docs/release.md` for main-first preparation, native ReleaseKit commands,
|
### Consumer Verification and Test Maintenance
|
||||||
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
|
Update release integration coverage for the new selection, tool declaration,
|
||||||
version command and accepted decision. Keep the ADR's decision content intact.
|
CI image, and simplified wrapper. Remove assertions that elevate a particular
|
||||||
Record the adoption and maintainer workflow change in the next release note
|
dependency version, image spelling, or bootstrap implementation into a lasting
|
||||||
when that release is prepared.
|
prohibition on legitimate upgrades. Older-version fixtures can remain when they
|
||||||
|
protect tagged-version selection; do not replace every historical value.
|
||||||
|
|
||||||
Add ReleaseKit's selected source and LGPL-3.0-or-later notices to
|
Retain proportionate protection of product facts, target membership, native
|
||||||
`docs/oss/attribution.md` under the existing OSS policy. Reuse applicable license
|
argument/status forwarding, preparation failures, and tagged-source selection.
|
||||||
texts already present. Incorporating `buildinfo` does not change Audita's
|
Rely on upstream coverage for common release mechanics. Tests using synthetic
|
||||||
application license.
|
module downloads must use test-owned module caches.
|
||||||
|
|
||||||
## Verification and Completion
|
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.
|
||||||
|
|
||||||
Adoption is complete when:
|
## Scope Boundaries
|
||||||
|
|
||||||
- The released dependency and pinned tool are selected consistently, and the
|
This is a dependency, tooling, and release-policy upgrade. Transcript processing,
|
||||||
application builds with its default offline test suite passing.
|
application configuration, LLM behavior, and output formats retain their current
|
||||||
- Version output works without LLM setup and reports the injected version from
|
contracts. Keep optional validation and additional checks at their current
|
||||||
a ReleaseKit-built executable.
|
selections. Adding race, vet, formatting, Markdown, distribution, file-size, or
|
||||||
- The native profile and thin wrapper drive candidate checks and publication
|
new publication-destination checks is a separate deliberate choice.
|
||||||
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.
|
|
||||||
|
|
||||||
## Remaining Release and Deployment Work
|
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.
|
||||||
|
|
||||||
Prepare the first adopting release under the [release procedure](../release.md),
|
## Acceptance and Existing Evidence
|
||||||
including a release note explaining the maintainer workflow change. Resolve
|
|
||||||
outstanding adoption-review findings through the linked remediation record.
|
|
||||||
Version selection and publication timing remain release-preparation decisions.
|
|
||||||
|
|
||||||
Offline integration evidence and live delivery observations are distinct.
|
The upgrade is complete when the selected dependency and tool declaration are
|
||||||
Observe the shared workflow during the first adopting release and address any
|
consistent; the module minimum and release-build toolchain are recorded in their
|
||||||
deployment failures through ReleaseKit's delivery recovery. Check that the
|
canonical owners; the local wrapper and tagged CI integration use that selection;
|
||||||
tagged commit, hosted note with its licensing footer, selected Linux assets,
|
and the ordinary tests and required Linux builds pass. Version injection must
|
||||||
and checksums reach the intended destination. This observation is asynchronous;
|
still reach Audita's existing version command. Policy provenance, attribution,
|
||||||
CI success or asset availability does not become a source-release completion
|
and current documentation must describe the implemented upgrade accurately.
|
||||||
gate or require the publication command to wait.
|
|
||||||
|
|
||||||
The accepted ADR settles the architectural choice and standard workflow
|
The preceding review already passed ReleaseKit's full suite and a disposable
|
||||||
trade-offs. No significant feature decisions remain open. The next Audita
|
Audita upgrade's full suite on Go 1.26.8, after adjusting the current-version
|
||||||
version and publication timing belong to release preparation. The
|
assertion in that copy. Linux amd64 and arm64 compilation succeeded, and the
|
||||||
[implementation plan](implementation.md) owns the ordered execution steps and
|
new tool dependencies were absent from Audita's runtime dependency list. That
|
||||||
their verification; this roadmap owns the desired end state and adoption intent.
|
evidence supports feasibility; it does not substitute for verifying the final
|
||||||
|
implementation, simplified bootstrap, or real injected-version build.
|
||||||
|
|
||||||
Implementation completed 2026-10-07 at revision
|
Live Woodpecker/Gitea delivery was not exercised during review. Observe delivery
|
||||||
`5ac704c4c42fd23ed94b1f7351491ad580726db1`. The full Go suite and executable
|
asynchronously when the first upgraded release is published and address any
|
||||||
version path passed, and ReleaseKit built both selected Linux artifacts with
|
deployment failures through the shared recovery procedure. No significant
|
||||||
its native version smoke check passing. The profile, dependency and CI pins,
|
feature decisions remain open; implementation details and final release
|
||||||
wrapper, and parsed workflow were verified together. Audita's local release
|
preparation can be resolved within the agreed scope.
|
||||||
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.
|
|
||||||
|
|||||||
Reference in New Issue
Block a user