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
|
||||
**Status:** Implementation complete; first adopting release and live delivery
|
||||
observation pending.
|
||||
**Last updated:** 2026-10-08
|
||||
**Status:** Agreed scope; implementation pending.
|
||||
|
||||
## Purpose and Original Baseline
|
||||
## Purpose
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
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.
|
||||
This roadmap replaces the completed initial-adoption roadmap. It defines the
|
||||
upgrade's target state and required work; a later implementation plan can own
|
||||
ordered execution steps.
|
||||
|
||||
## Current Baseline
|
||||
|
||||
The adoption implementation is now present: `go.mod` selects ReleaseKit
|
||||
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.
|
||||
At Audita commit `17421bc5f352f3fdeb67561b2b60b49979822228`:
|
||||
|
||||
The [adoption review](remediation.md) records focused CLI and wiring-test
|
||||
findings and their resolution status. Remaining implementation corrections
|
||||
belong there. First-release delivery observation remains deployment work,
|
||||
separate from source-release completion.
|
||||
- `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.
|
||||
|
||||
## 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
|
||||
|
||||
- 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.
|
||||
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.
|
||||
|
||||
## 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
|
||||
atomic branch/tag push and lightweight tags for new releases. Existing released
|
||||
tags, notes, pages, and assets retain their historical contents.
|
||||
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.
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
## 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
|
||||
the lightweight `buildinfo` facade; release orchestration is exercised through
|
||||
the upstream executable. The sibling checkout is review material, not a
|
||||
production dependency replacement.
|
||||
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.
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
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.
|
||||
### Toolchain and CI
|
||||
|
||||
### 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
|
||||
`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.
|
||||
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.
|
||||
|
||||
### Publication and Binary Delivery
|
||||
### Release Policy and Documentation
|
||||
|
||||
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.
|
||||
Update `docs/policy/release.md` using the selected upstream 1.6 revision. Adopt
|
||||
upstream wording for shared requirements, remove template-only instructions,
|
||||
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
|
||||
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.
|
||||
Record the adopted version, local update date, and exact per-document upstream
|
||||
source. Keep mixed-revision policy attribution accurate rather than implying
|
||||
that the whole policy suite was refreshed. Existing public discovery links and
|
||||
unrelated policy adoption metadata remain applicable.
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
### 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`
|
||||
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.
|
||||
### Attribution
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
### 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,
|
||||
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.
|
||||
### Consumer Verification and Test Maintenance
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
## 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
|
||||
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.
|
||||
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.
|
||||
|
||||
## 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),
|
||||
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.
|
||||
## Acceptance and Existing Evidence
|
||||
|
||||
Offline integration evidence and live delivery observations are distinct.
|
||||
Observe the shared workflow during the first adopting release and address any
|
||||
deployment failures through ReleaseKit's delivery recovery. Check that the
|
||||
tagged commit, hosted note with its licensing footer, selected Linux assets,
|
||||
and checksums reach the intended destination. This observation is asynchronous;
|
||||
CI success or asset availability does not become a source-release completion
|
||||
gate or require the publication command to wait.
|
||||
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 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.
|
||||
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.
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
Reference in New Issue
Block a user