eric/ReleaseKit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Plan the release audit implementation

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-06 15:37:33 +00:00
parent e4be7fa699
commit a0cb466395
2 changed files with 518 additions and 41 deletions
Download Patch File Download Diff File Expand all files Collapse all files

78
docs/roadmap/audit.md
View File

@@ -1,7 +1,8 @@
# ReleaseKit pre-release audit
Date: 2026-10-06. Reviewed source: `536a57916f6565ae8194c4563577dfcebd6cfb69`.
Status: review findings and proposed changes, revised for the clarified product goals.
Status: historical review evidence and selected target direction for the
[implementation plan](implementation.md).
Audience: maintainers deciding the shared release standard before `v0.1.0`.
## Assessment
@@ -115,8 +116,8 @@ configuration. Preserve caches and legitimate dependency preparation settings.
Share internal Go-environment handling where the semantics match. Preserve
the settings appropriate to native tests and static release builds separately.
Apply the same baseline to ReleaseKit's own profile. Retain a regression showing
that a failing test remains effective under an ambient filter. F4 and Open Question 1 address how
intentional product-specific checks should compose with this baseline.
that a failing test remains effective under an ambient filter. F4 and Design
Choice 1 describe how product-specific checks compose with this baseline.
### F2 — High: automatic push recovery can query a different endpoint and report false absence
@@ -174,7 +175,7 @@ settings that affect expected compatibility or validation. Keep the application
profile focused on its package, binary name, and targets. Exact toolchain
pinning and detailed build metadata remain optional operational choices.
When a retry requires the original bytes, preserve and reuse those artifacts.
Open Question 2 compares local toolchain use with a centrally maintained build
Design Choice 2 compares local toolchain use with a centrally maintained build
environment for consumers that benefit from shared setup.
### F4 — Design priority: adding a custom check replaces the entire standard suite
@@ -195,8 +196,8 @@ to preserve one suite run.
product-specific checks. Move redundant suite invocations out of consumer scripts.
Retain checks for actual product behavior, such as PromptKit's examples. Add
alternative test-invocation settings when a concrete consumer requirement
justifies them. This proposal changes the current customization contract; Open
Question 1 records the replacement-callback alternative.
justifies them. This choice changes the current customization contract; Design
Choice 1 records the replacement-callback alternative.
### F5 — Design priority: the CLI owns reusable tagged-build delivery orchestration
@@ -219,7 +220,7 @@ source before expensive compilation, then retain the necessary checks before
remote effects. Let the CLI adapt JSON, credentials, and output to that operation.
Use the same build declaration for candidate validation and delivery. Support
caller-provided builds for concrete needs such as retrying with retained
artifacts, as discussed in Open Question 3. Keep separate building useful for
artifacts, as discussed in Design Choice 3. Keep separate building useful for
local development. The ordinary consumer workflow should complete delivery in
one invocation; advanced artifact handoffs can use private coordination data
when needed.
@@ -241,11 +242,12 @@ publication and CI delivery.
**Recommendation.** Provide one maintained integration entry point and one
default delivery sequence for source-only and binary profiles. Consumers select
the ReleaseKit version, supply product settings, and provision credentials.
Centralize installation and update instructions. Choose source installation or a
maintained image according to the setup and maintenance effort each saves.
Centralize installation and update instructions. Use versioned source
installation for the shared CI command. Evaluate a maintained image by the
additional setup and maintenance effort it saves.
Keep dependency preparation separate from offline validation/builds. A split
build/delivery flow remains useful for an actual credential boundary or artifact
handoff. See Open Question 4 for packaging alternatives.
handoff. See Design Choice 4 for packaging alternatives.
`TestWoodpeckerDeliveryCommandSequences` in
[the CLI workflow tests](../../cmd/releasekit/woodpecker_test.go) executes
@@ -276,9 +278,8 @@ reporting and automation.
**Recommendation.** Prefer mutually exclusive current-outcome categories:
confirmed matching, uploaded, known pending, conflicting, and uncertain. Move an
asset out of pending when its outcome becomes uncertain or conflicting, and
clarify the facade GoDoc. Alternatively, explicitly define pending as a superset
of all unfinished assets and implement that rule consistently; see Open
Question 5. Update behavioral tests to protect the selected meaning.
clarify the facade GoDoc. Design Choice 5 records the alternative superset
interpretation.
### F8 — Maintainability: artifact rules have several implementation owners
@@ -301,7 +302,7 @@ from receipt and delivery adapters. Share Go invocation/environment construction
where the semantics match. Keep the explicit facade conversions required
by the ADR. Focus refactoring on the small internal helpers that own these rules.
## Recommended standard and release sequencing
## Target state
Retain the existing source transaction: committed stable-version note, clean
`main`, candidate already on authoritative `main`, one validation, selected-target
@@ -316,31 +317,24 @@ ReleaseKit owns the standard suite, routine build settings, delivery sequence,
and recovery reporting. Product developers choose versions and write
compatibility notes. Evaluate each proposed setting by the work it saves them.
Recommended order:
1. Fix F1–F2 and retain focused behavioral regressions before tagging `v0.1.0`.
2. Settle the validation and delivery API choices in Open Questions 1 and 3.
Adopt clear result categories under Question 5. Implement the selected
changes with their canonical documentation and consolidate F8 in those owners.
3. Address F3 through internal compatibility defaults, using Open Question 2 to
keep build configuration proportionate to actual consumer needs.
4. Exercise one source-only consumer with an extra product check and one binary
consumer through the common integration. Measure removed scripts, duplicated
tests, setup steps, and recurring release decisions. Keep ReleaseKit's default
suite independent of sibling checkouts.
5. Choose the simplest shared installation and update path under Open Question 4.
Verify the maintained integration during deployment preparation. Follow the
existing maintainer procedure for the release note and source publication;
report hosted delivery separately.
The [implementation plan](implementation.md) owns the stages, API changes,
regression coverage, and completion criteria needed to reach this target.
Representative adoption should demonstrate fewer scripts, duplicated tests,
setup steps, and recurring release decisions.
Feature expansion should follow demonstrated consumer needs and measurable
reductions in application maintenance or developer effort.
## Open Questions
## Design Choices
The implementation plan selects the recommended directions below for the
upcoming sprint. Alternatives record the tradeoffs for future consumer needs.
These choices describe the target behavior; current contracts change as their
implementation lands.
### 1. Should product checks supplement or replace standard validation?
**Recommended:** Run the shared offline Go suite once, followed by optional
**Selected direction:** Run the shared offline Go suite once, followed by optional
product-specific checks. ReleaseKit owns the command and its routine environment
settings. Migrate repeated suite invocations out of application scripts. Add
alternative invocation settings when an actual consumer requirement establishes
@@ -356,8 +350,8 @@ specific consumer need.
### 2. How should ReleaseKit choose build settings?
**Recommended:** Use the available compatible Go toolchain, ordinary baseline CPU
settings, and shared build flags. Handle incidental environment settings internally
**Selected direction:** Use the available compatible Go toolchain, ordinary
baseline CPU settings, and shared build flags. Handle incidental settings internally
so developers can rely on the selected target's expected compatibility. Keep
application configuration small. Toolchain-dependent byte differences are
acceptable; digest checks preserve existing published content, and retained
@@ -373,7 +367,7 @@ Explicit hardware variants can be added for a demonstrated product need.
### 3. Should the library own build-and-deliver, or accept only completed builds?
**Recommended:** Provide one facade operation for tagged-source verification,
**Selected direction:** Provide one facade operation for tagged-source verification,
selected-target builds, temporary storage, checksums, uploads, and cleanup.
Use it from the CLI so both interfaces share the procedure. Retain separate
building for local development and support prebuilt delivery where a concrete
@@ -389,11 +383,13 @@ operational separation they need.
### 4. How should the shared executable and CI integration be distributed?
**Recommended:** Choose the simplest maintained entry point for installation,
updates, and delivery. Begin with versioned source installation if it keeps
consumer integration small. Centralize reusable setup and provide one clear
upgrade procedure. Applications should select a ReleaseKit version and supply
product settings and credentials; shared integration should own routine setup.
**Selected direction:** Choose the simplest maintained entry point for installation,
updates, and delivery. Use versioned source installation and a shared CI delivery
command. The command prepares the tagged checkout, reads its product profile,
prepares dependencies for selected binaries, and invokes ordinary facade delivery.
Centralize reusable setup and provide one clear upgrade procedure. Applications
select a ReleaseKit version and supply product settings and credentials; shared
integration owns routine setup.
Assess packaging by the consumer code and recurring developer work it removes.
**Viable alternative:** Publish a maintained CI image containing ReleaseKit and
@@ -405,7 +401,7 @@ applications a small configuration and a routine invocation.
### 5. How should delivery results support simple recovery?
**Recommended:** Use exclusive outcome categories: matching, uploaded, known
**Selected direction:** Use exclusive outcome categories: matching, uploaded, known
pending, conflicting, and uncertain. Present ordinary callers with completion or
a clear failure and recovery instruction. Keep asset details available for
diagnostics. Derive recovery guidance centrally so each application can present

481
docs/roadmap/implementation.md Normal file
View File

@@ -0,0 +1,481 @@
# ReleaseKit audit implementation plan
Status: planned; implementation has not started.
Baseline: `e4be7fa` (2026-10-06). The [audit](audit.md) records the evidence,
product goals, and selected direction. This document owns implementation order
and completion criteria for that work.
## How to execute this plan
Implement one numbered stage per prompt, in order. Each stage includes its
production change, relevant tests, and current-contract documentation. Leave the
repository compiling and its checks passing at each stage boundary. Record
completed stages here with a concise validation result; report the commit
identifier in the stage completion response. Read
[development guidance](../development.md) and its applicable policies at the
start of each stage.
Use the [agent policy](../policy/agents.md), [architecture
policy](../policy/architecture.md), [testing policy](../policy/testing.md), and
[documentation policy](../policy/documentation.md). Discover current symbols
through the codebase graph, then inspect their callers and tests before editing.
The paths below locate the baseline; internal names may evolve during the work.
Use ordinary functions and existing internal packages where their ownership
fits. Public named types remain facade-owned with explicit internal conversions.
For each stage, run focused behavioral tests for its changed responsibilities.
Then run the existing repository checks from the root:
```sh
GOTOOLCHAIN=local GOPROXY=off GOSUMDB=off go test -mod=readonly -count=1 ./...
GOTOOLCHAIN=local GOPROXY=off GOSUMDB=off go run ./internal/apicheck
```
Prepare dependencies before these offline checks when needed. Review changed
GoDoc, examples, local documentation links and fragments, and `git diff --check`.
Reuse successful checks for unchanged content. Commit each completed stage
under the agent policy. These implementation checks serve the development
workflow.
## Decisions for this sprint
These choices resolve the audit's design alternatives for implementation:
- Candidate validation runs the standard offline Go suite once, then optional
product checks, then selected-target build verification. Rename the Go
callback to `AdditionalChecks`; JSON retains `checks` with additive semantics.
- ReleaseKit uses the available compatible Go toolchain, internal baseline CPU
settings, and shared build flags. It controls incidental flags and persistent
Go settings while preserving operational configuration such as caches.
- `Deliver` accepts a build declaration and owns temporary build output,
checksums, uploads, and cleanup. An explicit prebuilt path retains original
artifacts for retries and supports separated build/delivery environments.
- Delivery asset categories are disjoint observations: matching, uploaded,
known pending, conflicting, and uncertain. Existing overall delivery states
and content-preservation rules remain authoritative.
- A versioned source-installed command is the initial shared CI entry point.
Add `ci-deliver` for explicit CI checkout and dependency preparation followed
by the same facade delivery operation. Ordinary `deliver` remains suitable
for an already prepared checkout. CI images remain an operational option.
- Shared artifact rules and Go execution settings have small internal owners.
Application profiles continue to declare product facts and additional checks.
The callback and delivery request changes are deliberate pre-release API
changes. Update all in-repository callers and their canonical documentation in
the corresponding stage. The initial release note should describe the final
interfaces and migration impact when that release is prepared.
The sprint preserves the existing source transaction, successful-tag-push
completion point, bounded recovery, content-aware retries, standalone `Build`,
and lightweight `buildinfo`. Build observations and private receipts retain
their existing source-eligibility meaning. Toolchain-dependent byte differences
remain acceptable. Build identity remains an observation of the checked source
and produced files under the existing contracts. Live deployment and sibling
repository migrations remain separate adoption work in the
[product roadmap](releasekit.md).
## Stage 1 — Keep ambiguous-push recovery on the captured endpoint
**Covers:** F2. **Primary owners:** `internal/git/tag.go`,
`internal/git/remote.go`, `internal/publish/publish.go` and their tests.
1. Before `Endpoint.QueryTag` performs its remote read, reuse
`verifyScopedURLs` with the captured endpoint and command-scoped configuration.
Verify that the captured URL still resolves to itself. Use the existing
reconciliation context and timeout for both verification and the remote read.
2. Treat verification failure as unreadable authoritative state. Preserve error
identity through wrapping so `reconcilePush` reports `unknown`, retains the
local tag, and preserves the original push failure for diagnosis.
3. Keep the captured endpoint as recovery's authority. The local resolution
check precedes the existing single remote tag query. Preserve exact tag-object
and peeled-commit comparison and successful push as the completion point.
4. Update relevant recovery GoDoc and internal guidance to explain the
automatic URL-resolution check. Keep the manual recovery runbook consistent.
**Completion evidence:** Extend the existing local Git publication fixtures with
F2's lost-acknowledgment reproduction: actually publish the tag, install a URL
rewrite to an empty bare repository, then report a push error. Recovery must
return unknown and preserve the tag/error; direct inspection of the original
remote must find the intended object. Existing unchanged-endpoint success,
absence, conflict, and unreadable-recovery tests continue to pass. Test the
behavior through publication; avoid a second copy of the full recovery matrix.
## Stage 2 — Own effective Go settings for validation and builds
**Covers:** F1, F3, Go-environment portion of F8. **Primary owners:**
`internal/candidate/check.go`, `internal/build/build.go`, `internal/process/`,
and a small new `internal/gotool` package.
1. Put effective Go-environment construction and common invocation behavior in
`internal/gotool`. Reuse the existing subprocess boundary for context,
working directory, output, and error handling. Support native validation and
static target builds as distinct modes of the same implementation.
2. Account for both the process environment and values from Go's persistent
environment file. Resolve effective Go configuration with the installed Go
command under local toolchain selection and a controlled `GOFLAGS`. Ensure
configuration discovery itself tolerates the ambient settings being replaced;
an experiment override used only for discovery must not become the build
default. Carry effective operational settings into child environments, then
use `GOENV=off`
there so removed settings cannot reappear from the persistent file. Retain
ordinary process variables and effective cache, module-cache, temporary,
tool-location, and native C-tool settings. Keep informational `go env` output
separate from configuration when constructing child environments.
3. Own `GOFLAGS`, `GOWORK`, `GOTOOLCHAIN`, module-network settings, target
selection, experiment selection, and architecture-feature settings. Standard
validation uses `go test -mod=readonly -count=1 ./...`, host OS/architecture,
`GOWORK=off`, `GOTOOLCHAIN=local`, `GOPROXY=off`, `GONOPROXY=none`, and
`GOSUMDB=off`. Resolve the Go host target independently of ambient cross-build
settings. Native tests retain native Go cgo behavior and explicit native
C-tool configuration; release builds retain `CGO_ENABLED=0`.
4. Clear ambient experiments and architecture tuning for the child so the
selected Go toolchain supplies ordinary baseline defaults. Handle the Go
feature variables for supported toolchains, including `GOAMD64`, `GOARM`,
`GOARM64`, `GO386`, `GOMIPS`, `GOMIPS64`, `GOPPC64`, `GORISCV64`, and `GOWASM`.
Clearing must take effect for persisted values as well. Retain the existing
release flags, linker injection, target selection, and native version smoke
check. Keep these settings internal; the profile needs no new tuning fields.
5. Route default validation, build toolchain/host queries, target compilation,
and native smoke-build compilation through the shared owner. Preserve useful
compiler diagnostics and cancellation. Custom product commands retain their
explicitly selected arguments and environment overlays.
6. Update the build and check consumer guides and relevant GoDoc with the
supported behavior: shared baseline settings and the available compatible
toolchain. Exact internal environment construction belongs in internal docs.
**Completion evidence:** A genuinely failing fixture test still fails with
`GOFLAGS=-run=^$` supplied through either the process or a temporary Go env file.
An ambient cross-target setting still results in host-native validation. Extend
existing build fixtures to demonstrate that ambient/persisted `GOAMD64=v2` and
experiment settings do not alter the selected baseline build settings. Inspect
build metadata where useful; identical binary bytes are unnecessary evidence.
Use a temporary configured cache to demonstrate that persistent cache choices
survive. Preserve existing version injection, empty-target, cancellation, and
partial-build behavior. Fixtures use temporary Go configuration and never edit
the developer's persistent settings.
## Stage 3 — Make product checks additive
**Covers:** F4 and ReleaseKit's own F1 exposure. **Primary owners:** `check.go`,
`publish.go`, `internal/candidate/`, CLI profile mapping and fixtures.
1. Rename `ReleaseRequest.Validate` to
`AdditionalChecks func(context.Context, Candidate) error` and update the
corresponding internal request and facade conversions. The callback keeps
the existing candidate-value ownership and error-wrapping behavior.
2. Make `candidate.Validate` always run the shared offline suite first. On
success, invoke `AdditionalChecks` once when supplied. Run selected-target
build verification after these checks through the existing orchestration.
A failure or cancellation ends the sequence and preserves its cause.
3. Retain `checks` in JSON as ordered additional commands. Map the CLI's
`RunChecks` callback to `AdditionalChecks`. Keep the existing argument-vector
and per-command environment semantics.
4. Remove repeated standard-suite commands from `releasekit.json` and example
profiles. Preserve additional checks that address actual product behavior.
Update in-repository callback callers and fixtures to provide small valid Go
modules with an effective default suite. A callback fixture must exercise
its intended callback behavior after that suite succeeds.
5. Update facade GoDoc, `docs/config.md`, `docs/cli.md`, check/publish consumer
guides, examples, and affected internal documentation. Explain migration:
rename the callback and remove standard-suite invocations from custom checks.
**Completion evidence:** Through the public facade, prove that a failed standard
suite prevents the additional callback and publication, that an additional
failure prevents publication while preserving error identity, and that a
successful publication runs the standard suite and additional checks once for
its captured candidate. Reuse existing mutation/recheck tests with the new
callback. One CLI profile test covers ordered extra commands. Keep callback
unit coverage and end-to-end suite-count coverage at distinct boundaries.
## Stage 4 — Consolidate artifact identity and declaration rules
**Covers:** artifact portion of F8. **Primary owners:** `internal/build/`,
`internal/delivery/assets.go`, `cmd/releasekit/internal/cli/receipt.go`.
1. Add a small internal artifact-contract owner for target normalization,
filename-component validation, artifact names, and the expected declaration
for a build. Choose `internal/artifact` for these shared pure rules.
2. Move the existing rules from builder, receipt, and delivery into that owner.
Preserve accepted inputs, target order/deduplication, filenames, manifest
naming, and validation meaning. Keep build execution in `internal/build`,
hosted-content checks in delivery/Gitea, and receipt JSON/path handling in
the CLI adapter.
3. Use ordinary conversions at facade and receipt boundaries. Preserve
facade-owned public types and the current private receipt format. Consolidate
repeated declaration comparisons while retaining boundary-specific checks
for repository, commit, version, file location, and actual file contents.
4. Update the internal package inventory. Keep exact public build/result
contracts in GoDoc and private receipt lifecycle in its existing owner.
**Completion evidence:** Existing build-to-receipt-to-delivery tests retain
behavior for normalized targets, filenames, altered files, mismatched identity,
and manifests. Add only missing coverage for disagreement between these
boundaries. The API/dependency checker confirms that the shared internal owner
has not leaked through exported signatures or runtime dependencies.
## Stage 5 — Make delivery outcomes disjoint and actionable
**Covers:** F7. **Primary owners:** `internal/gitea/upload.go`, delivery result
GoDoc, CLI delivery reporting, and their tests.
1. Define the five collections as current observations for each reported asset.
`Matching` means existing matching content; `Uploaded` means confirmed upload
during this invocation; `Pending` means known missing work; `Conflicting`
means a detected conflict; `Uncertain` means unresolved state. Each asset
appears in at most one collection in a returned result.
2. In every upload/reconciliation branch, remove an asset from `Pending` when
moving it to matching, uploaded, conflicting, or uncertain. In particular,
fix failed reconciliation reads, conflicts, and unresolved writes. Later
known-missing assets can remain pending when an earlier upload stops work.
3. Preserve the existing overall delivery states and their handling of remote
writes. Early failures can return incomplete asset information. Category
exclusivity establishes no claim that every declaration has been observed.
4. Keep concise state-based recovery guidance in one CLI formatter: correct
local/preflight failures before retrying; retry partial delivery after fixing
its cause; resolve uncertain remote state before retrying; investigate
conflicting content and use a new version when source or published contents
require correction. Mention retained original artifacts when a rebuild would
conflict. Go callers use the documented overall state and asset categories.
5. Update delivery GoDoc, `docs/cli.md`, the delivery consumer guide and Gitea
integration documentation. Keep diagnostics available alongside the summary.
**Completion evidence:** Update the existing reconciliation-read-failure test
that currently expects overlap. Extend existing upload tests to cover conflict,
missing-after-ambiguous-upload, matching-after-lost-acknowledgment, and later
pending assets. Assert category exclusivity and meaningful overall state at the
upload boundary. CLI tests verify recovery meaning and exit classification
without freezing full diagnostic wording.
## Stage 6 — Give the facade ownership of build-and-deliver
**Covers:** F5. **Primary owners:** `delivery.go`, `internal/delivery/`,
`internal/build/`, and existing temporary-directory helpers.
1. Change `DeliveryRequest.Build` to `*BuildSpec`. Add
`Prebuilt *BuildResult` and `Output io.Writer`. `Build` requests managed builds;
`Prebuilt` supplies an existing result. Supplying both is an invalid request
because the operation needs one artifact source. With neither, or with an
empty selected target set, ordinary delivery is page-only. Preserve the
existing handling of empty prebuilt results.
2. Implement the reusable orchestration inside `internal/delivery`; the public
facade performs conversions. Verify version, product, local tag/HEAD
agreement, checkout cleanliness, and the committed release note before
compilation. Preserve historical lightweight-tag and detached-HEAD support.
3. For nonempty `Build`, create temporary output outside the worktree using the
existing helper, invoke the shared builder, and feed its result into the
existing asset validation/delivery path. Defer cleanup for success, failure,
and cancellation. Return diagnostic progress through `Output`; managed
temporary paths have no caller-owned lifetime.
4. Before hosted writes, retain the tagged-source eligibility check and the
build-result, file-digest, and manifest checks. A checkout change during the
build must fail eligibility. Use the same captured tag commit to read the
note and validate the build. Reuse the existing builders and delivery client.
5. `Prebuilt` retains caller-owned files and existing source/identity/content
checks. Its build result declares its targets as today. The CLI continues
comparing receipts with the selected profile. This path supports original
bytes across retries; callers own retention and cleanup.
6. Keep pre-remote build/preflight failures `DeliveryNotAttempted`. Preserve
candidate identity when known, wrapped error causes, cancellation, and the
current mapping of hosted failures and partial progress.
7. Update all Go callers for the request shape. As an intermediate step, map
the CLI's current already-built result to `Prebuilt`; Stage 7 removes that
duplicate orchestration. Update delivery GoDoc and the consumer guide with
the normal `Build` path and the explicit `Prebuilt` lifecycle.
**Completion evidence:** Add facade-level tests using a real small Go consumer
and a local HTTP server for managed binary delivery and page-only delivery.
Prove invalid tagged source fails before Go compilation or hosted writes,
build failure prevents hosted writes, and managed temporary output is cleaned
on success and failure. Extend existing mutation/cancellation coverage where
needed. Preserve prebuilt retry, digest conflict, note conflict, and source
eligibility coverage. Confirm the two facades' dependency boundaries.
## Stage 7 — Route ordinary CLI delivery through the facade
**Covers:** the CLI portion of F5. **Primary owners:**
`cmd/releasekit/main.go`, CLI receipt adapters, CLI tests and documentation.
1. Change ordinary `runDelivery` to pass the configured `BuildSpec` and output
writer directly to `Deliver`. Remove its temporary-directory and standalone
build coordination. Keep profile parsing, credential lookup, presentation,
and exit-code selection in the CLI.
2. Retain `build --output` and `deliver --assets`. The latter loads and verifies
the private receipt, compares it with the selected profile, and supplies
`Prebuilt`. Keep stale-receipt invalidation and standalone build behavior.
3. Share the final CLI-to-facade delivery adapter so the CI entry point in Stage
9 can use it after preparation. Keep ordinary `deliver` free of dependency
downloading and checkout mutation.
4. Update CLI/configuration guidance and examples to make one `deliver`
invocation the normal path. Describe split build/delivery for retained bytes
and credential separation. Preserve exit statuses 0, 1, 2, and 3.
**Completion evidence:** CLI tests cover source-only and binary profiles,
preflight failure before compilation, token/profile errors, and the explicit
receipt path. Reuse Stage 6 for domain failure coverage. Confirm the maintained
ordinary command exercises the facade-owned lifecycle and reports F7's results.
## Stage 8 — Add reusable CI preparation operations
**Covers:** preparation ownership in F6. **Primary owners:** a new root
`preparation.go`, `internal/git/`, `internal/gotool/`, and a small internal
preparation coordinator.
1. Add facade-owned `TaggedCheckoutRequest` with `RepositoryDir`, `Version`,
`Remote`, and `ExpectedCommit` strings, and
`PrepareTaggedCheckout(context.Context, TaggedCheckoutRequest) error`.
An empty remote selects `origin`. This is an explicit preparation operation
for disposable CI checkouts; ordinary delivery keeps its current behavior.
2. Validate the version and required expected commit before mutation. Fetch
the selected tag from the selected remote with an explicit tag refspec,
verify that its peeled commit equals the expected CI commit, detach checkout
at that commit, and verify HEAD agreement. Use the existing Git subprocess
boundary and preserve Git errors. Use ordinary checkout/fetch behavior;
conflicting local changes or tags are reported for the operator to resolve.
3. Add `PrepareBuildDependencies(context.Context, string) error`, taking the
repository directory. Internally run `go mod download` with the available
compatible local Go toolchain and workspace discovery disabled. Preparation
uses the caller's dependency-access settings, including proxy/private-module
configuration and caches. This operation is explicitly network-capable.
Keep offline test/build environments from Stage 2 distinct from preparation.
4. Keep both operations behind the root facade with internal implementations.
These two additions serve the concrete shared CI workflow and Go consumers
with the same preparation needs. Keep their API small: CI-provider variables,
JSON profile loading, credentials, and output formatting stay in adapters.
5. Add GoDoc and a short preparation section to the delivery consumer guide;
update the internal package inventory. State filesystem/network effects and
cancellation behavior. Preparation does not publish a tag or hosted content.
**Completion evidence:** Local Git fixtures verify expected-commit agreement,
wrong-tag rejection before checkout, detached checkout, and ordinary local
conflict behavior. A subprocess-boundary test verifies dependency preparation
uses the repository and preparation environment and propagates failure and
cancellation. Keep default tests offline with a local module cache or a small
Go-command fixture; no live module server is needed.
## Stage 9 — Add the shared CI delivery command
**Covers:** the shared command portion of F6.
**Primary owners:** CLI parsing/routing, CLI command tests, `docs/cli.md`,
and `docs/config.md`.
1. Add:
```text
releasekit ci-deliver [--repo DIR] [--config FILE] [--remote NAME] --commit OID VERSION
```
Options precede the version, consistent with existing commands. Repository
and profile defaults match `deliver`; remote defaults to `origin`. The
explicit command authorizes preparation of the selected CI checkout.
2. Call `PrepareTaggedCheckout`, then load the profile from that checked-out
source, then validate the selected delivery configuration and credentials.
When the profile selects binaries, call `PrepareBuildDependencies`. Finish
through Stage 7's ordinary delivery adapter and `Deliver`. Page-only profiles
skip application dependency preparation and binary work. Read custom profile
paths under the existing CLI path rules.
3. Keep the provider adapter declarative: Woodpecker supplies `CI_WORKSPACE`,
`CI_COMMIT_SHA`, and `CI_COMMIT_TAG` as command arguments. The library and
ordinary CLI operations remain independent of Woodpecker environment names.
Preparation failures return 1; argument/profile/credential errors return 2;
final delivery uses the existing success/failure/unknown status mapping.
4. Update command usage, `docs/cli.md`, and configuration guidance for the new
entry point, its preparation effects, profile-loading order, and exit codes.
Keep ordinary `deliver` documented as operating on prepared source.
**Completion evidence:** Exercise the command with local Git/HTTP fixtures for
source-only and binary delivery. Prove the profile is read after checkout,
a wrong CI commit fails before application builds or hosted writes, and a
source-only module with unavailable dependencies still reaches page delivery.
Reuse facade tests for the individual preparation and delivery operations.
## Stage 10 — Consolidate and exercise maintained CI templates
**Covers:** installation, workflow duplication, and artifact-testing in F6.
**Primary owners:** `examples/woodpecker/`, CLI workflow tests, installation
instructions, and the product roadmap.
1. Select versioned source execution as the default bootstrap:
`go run gitea.maximumdirect.net/eric/ReleaseKit/cmd/releasekit@PIN ci-deliver ...`.
`PIN` is an immutable ReleaseKit revision or published version. Applications
choose a compatible Go/Git image and provision the delivery token. The shared
command owns checkout checks, conditional dependency preparation, and delivery.
The normal Go caches suffice; optional CI cache mounts remain deployment
configuration. Document `go install ...@PIN` for a locally retained executable
and one upgrade procedure based on changing the selected version.
2. Consolidate source-only and binary Woodpecker templates into one maintained
`examples/woodpecker/tag-delivery.yml`, with the product profile selecting
page-only or binary behavior. Remove the two superseded templates and repair
their links. Retain the distinct first-release bootstrap in
`releasekit-source-delivery.yml`, since ReleaseKit's own first source release
must build its tool from the tagged source. Simplify it around the shared
command where this preserves that bootstrap.
3. Replace tests that reconstruct the workflow commands with checks tied to the
maintained artifact. Use a small extractor for the template's one command
block and execute it with controlled CI variables, local Git/HTTP fixtures,
and a Go bootstrap shim that maps the pinned remote tool invocation to the
CLI built from the test checkout. Validate the module/command/version
arguments in the shim. Apply the template's matrix substitutions and
Woodpecker dollar escaping before shell execution. Keep the template subset
simple enough for a small test helper; a general YAML runner is unnecessary.
4. Document bootstrap requirements, token provision, compatible Go selection,
optional caches, dependency preparation, and the version upgrade procedure.
Align `releasekit.md`'s remaining adoption work with source installation;
identify live deployment and the real immutable pin as remaining work.
**Completion evidence:** Execute the actual maintained command block for both
source-only and binary fixture delivery. A repeated invocation preserves
matching remote content. The bootstrap shim proves template wiring, not
published-module availability. Record that distinction and retain real
installation/live Woodpecker verification as deployment work.
## Stage 11 — Validate representative adoption and close the sprint
**Covers:** audit-wide acceptance and adoption evidence. **Primary owners:**
existing external-consumer fixtures, consumer guidance, this plan, and the
remaining-work section of `releasekit.md`.
1. Exercise a source-only consumer with one meaningful extra check and a binary
consumer using `buildinfo`, selected targets, and Gitea delivery. Reuse and
extend the fixtures from prior stages. Verify publication through local Git
remotes and delivery through local HTTP fixtures as separate operations.
2. Review available sibling projects named by the product roadmap read-only.
Use PromptKit and Narratio as the source-only and binary representatives.
Record a concise migration assessment: retained product settings/checks,
release code and repeated tests that can be deleted, runtime-version
adaptation, and required policy
or procedure changes. Label projected deletions as estimates. If a sibling
checkout is unavailable, use the audit evidence and label its verification
date. Keep implementation tests self-contained in ReleaseKit.
3. Assess the final user workflow against the audit: standard tests once,
additional checks declared once, one ordinary delivery invocation, one
versioned CI entry point, clear recovery, and shared artifact/build rules.
Address implementation gaps within their existing stage scope before closing
the sprint. Record any new product decision as such.
4. Reconcile GoDoc, CLI/configuration references, consumer guides, maintained
examples, internal inventory, and the product roadmap with implemented
behavior. Keep the audit's original evidence historical. Record completion
here and link to the remaining adoption/deployment work.
5. Run the standard offline suite and API checks on the final implementation.
Run them with the minimum supported Go 1.25 toolchain when available in the
implementation environment; otherwise record that verification limitation
explicitly. Minimum-version verification is evidence about the existing
module requirement, rather than a new permanent release matrix.
6. Leave source publication, real installation verification, credentials,
workflow activation, live service checks, and changes in sibling repositories
for their deployment/adoption tasks. Follow the maintainer release procedure
when a release is separately requested. Keep ReleaseKit's own deliverables
source-only under the current release policy.
**Completion evidence:** A concise final record identifies the passing checks,
representative workflows, projected adoption savings, implemented API/profile
migration, and remaining deployment work. Every F1–F8 finding has an implemented
resolution and appropriately scoped evidence. Review and commit the final
changes with a clean worktree.
## Open Questions
No unresolved product choice is required to implement these stages. The
selected approaches and rationale are recorded in the audit's design choices.
Real deployment pins, credentials, service availability, and per-application
migration scheduling are inputs to subsequent deployment/adoption work. They
are separate from the implementation acceptance criteria above.