328 lines
19 KiB
Markdown
328 lines
19 KiB
Markdown
# Implementation Plan: ReleaseKit Adoption
|
||
|
||
**Last updated:** 2026-10-07
|
||
**Status:** Complete; Stages 1–5 complete.
|
||
**Audience:** Luna coding agent.
|
||
|
||
## Scope and Execution
|
||
|
||
Implement the target in the [ReleaseKit roadmap](releasekit.md), following
|
||
[ADR 0001](../adr/0001-releasekit.md). The roadmap owns intent and policy
|
||
choices; this document owns execution. The planning baseline is Audita commit
|
||
`418da456d75a68d3bb5a43ab823c5b2b434b90cc`: v3.0.0 is released, the ADR is
|
||
accepted, and release tooling still uses the custom scripts and delivery plugin.
|
||
|
||
This replaces the completed PromptKit plan. Its
|
||
[completion record](https://gitea.maximumdirect.net/eric/audita/src/commit/418da456d75a68d3bb5a43ab823c5b2b434b90cc/docs/roadmap/implementation.md)
|
||
remains available for historical adoption references.
|
||
|
||
Execute Stage 1 through Stage 5 in order. Each is a bounded Luna implementation
|
||
unit. Commit completed units with plain English messages under the
|
||
[agent policy](../policy/agents.md), recording the relevant checks. Intermediate
|
||
commits need not be release-ready; complete the migration directly without
|
||
compatibility wrappers for the old release arguments or temporary release modes.
|
||
|
||
Start with [development guidance](../development.md), use graph-first discovery,
|
||
and follow the applicable [architecture](../policy/architecture.md),
|
||
[testing](../policy/testing.md), [documentation](../policy/documentation.md),
|
||
[release](../policy/release.md), and [OSS](../policy/oss.md) policies. Preserve
|
||
transcript processing and its current configuration, reporting, and LLM behavior.
|
||
|
||
Use ReleaseKit v0.1.0, commit
|
||
`5e60fe3113c69f95c42fbbe32a8ca4b51f5b83c1`. The sibling checkout is reference
|
||
material. Its pinned [configuration](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.1.0/docs/config.md),
|
||
[CLI](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.1.0/docs/cli.md),
|
||
[build](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.1.0/docs/consumers/build.md),
|
||
and [delivery](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.1.0/docs/consumers/delivery.md)
|
||
contracts own generic mechanics. Keep Go 1.25.5 and unrelated dependency
|
||
selections. Use released modules without a production local replacement.
|
||
|
||
### Selected Implementation Decisions
|
||
|
||
- Audita imports `ReleaseKit/buildinfo` for runtime version information. The
|
||
upstream executable owns release orchestration; no application release engine
|
||
or private linker variable is needed.
|
||
- `releasekit.json` owns product facts. Local tooling builds the executable from
|
||
the module graph; CI pins the same v0.1.0 release explicitly.
|
||
- Keep `scripts/release.sh` as a thin entry point with native ReleaseKit
|
||
arguments, such as `publish VERSION` and `check VERSION`. Compile its tool into
|
||
ignored `bin/releasekit` and invoke it with `exec` to preserve native statuses.
|
||
- Main-first preparation, annotated tags, the offline standard suite, Linux
|
||
builds, and the native version smoke check are accepted. On a nonselected
|
||
host, the shared builder may compile a temporary native executable and require
|
||
its check to succeed. Keep only Linux amd64 and arm64 delivery targets.
|
||
- CI uses managed `ci-deliver` and the existing `GITEA_RELEASE_TOKEN` secret,
|
||
exposed to the command as `RELEASEKIT_GITEA_TOKEN`. Retained prebuilt artifacts
|
||
remain an upstream recovery option rather than a second ordinary CI sequence.
|
||
- Additional profile checks are omitted. Do not repeat the standard suite,
|
||
maintain a local Git/publication guard layer, or copy upstream delivery logic.
|
||
Focus tests on Audita wiring and reuse existing protection for common mechanics.
|
||
|
||
This implementation sprint does not choose an Audita release version, write a
|
||
new versioned release note, tag, push to the authoritative repository, contact
|
||
Gitea with delivery credentials, or wait for CI. Deployment observations belong
|
||
to the first adopting release and its separate delivery status. No extra release
|
||
gates or platform guarantees are introduced by these adoption checks.
|
||
|
||
## Stage 1 — Add the Dependency and Version Command [x]
|
||
|
||
**Primary files:** `go.mod`, `go.sum`, `internal/cli/run.go`, and focused tests in
|
||
`internal/cli`.
|
||
|
||
1. Add `gitea.maximumdirect.net/eric/ReleaseKit@v0.1.0` with `go get`. Import its
|
||
public `buildinfo` package in the CLI and run `go mod tidy` after the import
|
||
is present. Review the dependency diff for unrelated upgrades or replacements.
|
||
2. Add `version` dispatch to the existing CLI. With no arguments, print
|
||
`audita ` followed by `buildinfo.Version()` and a newline to stdout, returning
|
||
zero. Run this route independently of application configuration and runtime
|
||
assembly. Use the existing output streams and standard-library parsing style.
|
||
3. Add the command to root help. Support `help version` and the usual
|
||
`version -h`/`version --help` help behavior with stdout and status zero.
|
||
Unexpected positional arguments or unknown flags use the existing usage-error
|
||
status two. No new version flags are needed at the root level.
|
||
4. Add compact CLI coverage for successful version output, help, and malformed
|
||
invocation. Derive the expected version from the public accessor rather than
|
||
hardcoding `dev`. Exercise the version route from a temporary working directory
|
||
without application setup and verify stderr stays empty on success. Preserve
|
||
existing commands and help behavior.
|
||
|
||
**Verification and completion:** Run
|
||
`go test ./internal/cli ./cmd/audita`, build the application to ignored
|
||
`bin/audita`, and run its `version` command. Run `git diff --check`, review the
|
||
module diff, and commit. Real release-version injection is verified in Stage 5;
|
||
no test should hardcode an upstream private linker symbol.
|
||
|
||
**Completed 2026-10-07:** Added ReleaseKit v0.1.0 and the configuration-free
|
||
`audita version` command with root/help routing and usage-error handling.
|
||
Checks passed: `go test ./internal/cli ./cmd/audita`,
|
||
`go build -o ./bin/audita ./cmd/audita`, `./bin/audita version`, and
|
||
`git diff --check`.
|
||
|
||
## Stage 2 — Introduce the Product Profile and Thin Local Wrapper [x]
|
||
|
||
**Primary files:** new `releasekit.json`, `scripts/release.sh`, and
|
||
`scripts/release_test.go`.
|
||
|
||
1. Write a JSON profile with these exact product settings:
|
||
|
||
| Field | Value |
|
||
| --- | --- |
|
||
| `product` | `Audita` |
|
||
| `remote` | `origin` |
|
||
| `build.main_package` | `./cmd/audita` |
|
||
| `build.binary_name` | `audita` |
|
||
| `build.targets` | `linux/amd64`, `linux/arm64` |
|
||
| `delivery.base_url` | `https://gitea.maximumdirect.net` |
|
||
| `delivery.owner` | `eric` |
|
||
| `delivery.repository` | `audita` |
|
||
| `delivery.token_env` | `RELEASEKIT_GITEA_TOKEN` |
|
||
|
||
Omit `checks`. Store no token value and use the upstream profile format
|
||
directly; Audita does not need another profile parser in production.
|
||
2. Replace the wrapper body with straightforward Bash using `set -euo pipefail`:
|
||
select the repository directory relative to the script, create `bin/`, build
|
||
the selected CLI, and execute it with the original argument vector. The
|
||
build command is:
|
||
|
||
```sh
|
||
GOWORK=off GOTOOLCHAIN=local go build -mod=readonly \
|
||
-o ./bin/releasekit gitea.maximumdirect.net/eric/ReleaseKit/cmd/releasekit
|
||
```
|
||
|
||
Finish with `exec ./bin/releasekit "$@"`. Preserve argument boundaries and
|
||
build failures. Existing `bin/` ignore rules suffice. Let ReleaseKit parse
|
||
its commands and report errors; remove all local note, version, Git, test,
|
||
build-target, and publication mechanics from the wrapper.
|
||
3. Replace `TestReleaseWorkflow`'s old fourteen-scenario matrix. Use a temporary
|
||
layout with the real wrapper and a stub at the Go/tool boundary to verify
|
||
repository selection, forwarded native arguments (including an argument with
|
||
spaces), and returned tool status. Include uncertain publication status three
|
||
and a failed bootstrap that never executes the tool. The stub writes a small
|
||
executable at the requested output path; assert effects and arguments without
|
||
tying tests to harmless build-flag ordering or a particular shell layout.
|
||
4. Add a focused check of the committed JSON profile's product/build/delivery
|
||
facts and absence of additional checks or credential values. Standard JSON
|
||
decoding in test code is sufficient. Keep this coverage alongside wrapper
|
||
tests; compare target membership rather than incidental list order. Avoid
|
||
reproducing upstream profile validation or remote guard tests.
|
||
5. Keep `scripts/build-release.sh` until Stage 3 removes its CI caller. The new
|
||
wrapper already uses ReleaseKit's selected build specification.
|
||
|
||
**Verification and completion:** Run `go test ./scripts`, then
|
||
`bash scripts/release.sh version` to verify real tool bootstrap and execution.
|
||
This prints the tool's version, not Audita's. Check ignored build output and
|
||
`git diff --check`, then commit. No publication or delivery invocation against
|
||
an external service is needed.
|
||
|
||
**Completed 2026-10-07:** Added the Audita profile and replaced the local
|
||
publication workflow with a wrapper that builds and execs ReleaseKit. Replaced
|
||
the publication test matrix with focused wrapper and profile checks. Checks
|
||
passed: `go test ./scripts`, `bash scripts/release.sh version`, ignored-output
|
||
verification for `bin/releasekit`, and `git diff --check`.
|
||
|
||
## Stage 3 — Migrate Woodpecker Delivery and Retire the Builder [x]
|
||
|
||
**Primary files:** `.woodpecker/release.yml` and deletion of
|
||
`scripts/build-release.sh`.
|
||
|
||
1. Adapt the maintained upstream
|
||
[tag-delivery template](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.1.0/examples/woodpecker/tag-delivery.yml).
|
||
Use its matrix and single `deliver` step with `GO_IMAGE: golang:1.25.5` and
|
||
`RELEASEKIT_VERSION: v0.1.0`. Select tag events under `refs/tags/v*`.
|
||
2. Map the command environment variable `RELEASEKIT_GITEA_TOKEN` from the
|
||
existing Woodpecker secret `GITEA_RELEASE_TOKEN`. Use the existing credential;
|
||
no new secret name or credential provisioning is selected by this migration.
|
||
3. Use the template's command, preserving Woodpecker interpolation escaping:
|
||
|
||
```sh
|
||
go run gitea.maximumdirect.net/eric/ReleaseKit/cmd/releasekit@${RELEASEKIT_VERSION} ci-deliver \
|
||
--repo "$${CI_WORKSPACE}" \
|
||
--commit "$${CI_COMMIT_SHA}" \
|
||
"$${CI_COMMIT_TAG}"
|
||
```
|
||
|
||
ReleaseKit owns fetch/checkout verification, dependency preparation, builds,
|
||
note-page creation, manifests, and uploads. Remove the separate build step,
|
||
release plugin, wildcard asset settings, and local checksum configuration.
|
||
Managed delivery gets its targets and destination from `releasekit.json`.
|
||
4. Delete `scripts/build-release.sh` after confirming its active caller is gone.
|
||
Search remaining script/CI references and remove only obsolete active
|
||
invocations. Historical release records retain their original descriptions.
|
||
5. Review the parsed workflow against the template: selected image/pin, tag
|
||
trigger, token mapping, and event arguments. Use the existing YAML dependency
|
||
or available tooling for local syntax inspection. Confirm the tool pin matches
|
||
the selected module. This is adoption validation; it does not require a new
|
||
permanent workflow-text snapshot test or a running Woodpecker instance.
|
||
|
||
**Verification and completion:** Run `go test ./scripts`, review the workflow
|
||
and profile together, and run `git diff --check`. Commit the delivery migration.
|
||
The existing Go image must provide compatible Go and Git; real runner execution
|
||
is observed during subsequent delivery, independently of source completion.
|
||
|
||
**Completed 2026-10-07:** Migrated Woodpecker to the pinned managed
|
||
`ci-deliver` step using the existing secret, then removed the obsolete binary
|
||
builder. Verified the parsed workflow settings and command against the pinned
|
||
template, confirmed the module/workflow pins match, ran `go test ./scripts`,
|
||
confirmed no active CI or script caller remained, and passed `git diff --check`.
|
||
|
||
## Stage 4 — Align Policy, Documentation, and Attribution [x]
|
||
|
||
**Primary files:** `docs/release.md`, `docs/policy/release.md`, `docs/cli.md`,
|
||
`docs/internal/cli-config.md`, `docs/adr/README.md`, and
|
||
`docs/oss/attribution.md`. Update other current references only where affected.
|
||
|
||
1. Rewrite the runbook around dependency preparation, a committed candidate,
|
||
`git push origin main`, and `bash scripts/release.sh publish VERSION`.
|
||
Explain that remote `main` must identify the captured candidate exactly.
|
||
`bash scripts/release.sh check VERSION` is an optional local diagnostic,
|
||
never a required pre-publication step. Document preparation with
|
||
`GOWORK=off GOTOOLCHAIN=local go mod download`; if it changes module files,
|
||
those changes belong in the candidate before publication.
|
||
2. Describe annotated notes-derived tags, native publication statuses, and
|
||
recovery against the captured authoritative endpoint. State that the tool
|
||
retains a local tag after push failure. An exact-object recovery can confirm
|
||
success; an unreadable result remains unknown. Link to pinned upstream
|
||
recovery guidance instead of implementing or repeating its full algorithm.
|
||
Remove the old atomic-push prerequisite and procedure.
|
||
3. Describe the shared tagged-source delivery command, the existing secret
|
||
mapping, Linux artifacts, note body/footer, and separate delivery status.
|
||
Explain content-aware retries and retained-artifact recovery by linking to
|
||
upstream. Remove references to the retired builder/plugin and the assertion
|
||
that Audita has no version command. Keep the release script's bootstrap
|
||
preparation distinct from its offline candidate validation.
|
||
4. In the release policy, retain upstream wording wherever it already permits
|
||
the selected approach. Add a concise project-specific native-host check
|
||
provision under supported platforms/candidate validation: Linux delivery
|
||
targets remain required, macOS development remains best effort, and running
|
||
publication on a nonselected host requires ReleaseKit's temporary native
|
||
version check to succeed. Qualify the existing statement that macOS failures
|
||
never block release accordingly. Mac access and native tests on every target
|
||
remain unnecessary. Date the local policy update and preserve its upstream
|
||
source attribution. Avoid unrelated policy changes or additional gates.
|
||
5. Document `audita version`, its stdout/help/usage behavior, and public version
|
||
fallback in `docs/cli.md`. Add a short implementation/change-recipe note in
|
||
`docs/internal/cli-config.md` linking to that contract and the accepted ADR.
|
||
Update the ADR index to list ADR 0001; its current assertion that no ADR exists
|
||
is obsolete. Preserve the accepted ADR's content.
|
||
6. Add a House Format ReleaseKit entry with selected module v0.1.0,
|
||
`Copyright (C) 2026 Eric Rakestraw`, and `LGPL-3.0-or-later`. Link existing
|
||
`licenses/LGPL-3.0.txt` and `licenses/GPL-3.0.txt`, and the upstream COPYRIGHT
|
||
and source at commit `5e60fe3113c69f95c42fbbe32a8ca4b51f5b83c1`. Check the
|
||
selected module's notices. Keep the application grant and unchanged license
|
||
texts intact; no policy-template material is copied in this feature.
|
||
7. Repair current navigation affected by replacing this implementation plan.
|
||
Completed PromptKit/ConfigKit roadmap references that intend to identify
|
||
their former plan should link to the corresponding historical completion
|
||
records, not this ReleaseKit plan. Preserve published release notes and tags.
|
||
The next release note is deferred to release preparation.
|
||
|
||
**Verification and completion:** Check commands against the new wrapper/CLI,
|
||
local links and anchors, pinned upstream references, source attribution, and
|
||
`git diff --check`. Use the prior successful code checks for unchanged code.
|
||
Commit the documentation unit.
|
||
|
||
**Completed 2026-10-07:** Updated the ReleaseKit runbook, release policy,
|
||
version contract and contributor guidance, ADR index, and component attribution.
|
||
Repaired PromptKit and ConfigKit links to their historical implementation
|
||
records. Verified local links and anchors, release CLI and version commands,
|
||
pinned module/notices, source attribution, and `git diff --check`.
|
||
|
||
## Stage 5 — Verify Adoption and Close the Plan [x]
|
||
|
||
**Primary files:** This plan and the ReleaseKit feature roadmap; fix an
|
||
implementation file only if the final checks expose a real integration defect.
|
||
|
||
1. Audit the roadmap acceptance criteria against the landed files. Confirm the
|
||
runtime uses the public version accessor, the profile selects only the two
|
||
Linux targets, pins agree, the wrapper owns no common release mechanics, and
|
||
the old builder and repeated publication tests have been retired.
|
||
2. Prepare dependencies if necessary, then run `go test ./...` and
|
||
`go build -o ./bin/audita ./cmd/audita`. Run the normal binary's `version`
|
||
command without application setup. These tests remain offline; preparation
|
||
may use the module network separately.
|
||
3. On the committed implementation, verify the real shared builder once using
|
||
temporary output outside the repository:
|
||
|
||
```sh
|
||
releasekit_check_dir=$(mktemp -d)
|
||
bash scripts/release.sh build --output "$releasekit_check_dir" v0.0.0
|
||
```
|
||
|
||
`v0.0.0` is solely a build-test identifier, not an Audita release selection.
|
||
`build` requires no release note or remote publication. Confirm both
|
||
`audita-v0.0.0-linux-amd64` and `audita-v0.0.0-linux-arm64` are produced;
|
||
ReleaseKit's own mandatory native smoke check must report success. It checks
|
||
`audita v0.0.0` with a newline on a host-runnable executable, building a
|
||
temporary native executable itself when needed. Do not execute a foreign
|
||
architecture binary. Remove the temporary output afterward. The CLI's private
|
||
build receipt is an upstream artifact and should not enter Git.
|
||
4. Review the dependency/attribution diff, wrapper/profile wiring evidence,
|
||
workflow syntax and pin, and current documentation. Run `git diff --check`
|
||
and confirm no generated output, credentials, or unrelated work is staged.
|
||
Fix proven defects and rerun only affected checks. No real tag publication,
|
||
hosted upload, paid inference, extra platform matrix, or CI polling is needed
|
||
to establish this implementation's completion.
|
||
5. Mark the plan and feature roadmap complete after these requirements pass.
|
||
Record the tested implementation revision and checks; distinguish a later
|
||
documentation-only closure commit. Summarize the local infrastructure removed
|
||
and any remaining deployment observations accurately. Commit the closure.
|
||
The first adopting release and live delivery remain separate authorized work.
|
||
|
||
**End state:** Audita supplies a product profile, native version command, thin
|
||
local entry point, and shared CI invocation. ReleaseKit owns the common release
|
||
mechanics and their tests. Documentation and attribution match the integration.
|
||
No implementation-blocking open questions remain.
|
||
|
||
**Completed 2026-10-07:** Audited the adoption criteria against implementation
|
||
revision `5ac704c4c42fd23ed94b1f7351491ad580726db1`. Checks passed:
|
||
`go test ./...`; `go build -o ./bin/audita ./cmd/audita` followed by the binary's
|
||
`version` and `--help` commands; ReleaseKit's real `build` command produced
|
||
`audita-v0.0.0-linux-amd64` and `audita-v0.0.0-linux-arm64` and passed its
|
||
native version smoke check; profile, module/tool pins, wrapper, and parsed
|
||
Woodpecker workflow matched the selected integration; and `git diff --check`.
|
||
The closure record is a documentation-only commit after the tested
|
||
implementation revision. Audita's local build and publication mechanics and
|
||
their repeated-mechanics test matrix have been removed in favor of ReleaseKit.
|
||
The first adopting release and live Woodpecker/Gitea delivery observation
|
||
remain separate work.
|