Plan the ReleaseKit adoption
This commit is contained in:
377
docs/roadmap/implementation.md
Normal file
377
docs/roadmap/implementation.md
Normal file
@@ -0,0 +1,377 @@
|
||||
# ReleaseKit Adoption Implementation Plan
|
||||
|
||||
Implement the agreed [adoption roadmap](releasekit.md) in the stages below,
|
||||
in order. Each stage is scoped for one Luna coding-agent prompt. This document
|
||||
owns the implementation steps; the roadmap owns purpose and selected policy.
|
||||
|
||||
## Baseline And Working Rules
|
||||
|
||||
- Planning baseline: PromptKit commit
|
||||
`41b2021d8cd90b8dc15483f63fb1979642acad3a`. ReleaseKit is not yet a dependency;
|
||||
publication and validation live in `scripts/release.sh` and
|
||||
`scripts/release-check.sh`.
|
||||
- Select released ReleaseKit `v0.2.0`, whose commit is
|
||||
`e030794969fb7787e647a90bbc4eb81bd0610f07`. Use its
|
||||
[profile](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.2.0/docs/config.md),
|
||||
[CLI](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.2.0/docs/cli.md),
|
||||
and [candidate validation](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.2.0/docs/consumers/check.md)
|
||||
contracts. No upstream changes or sibling-checkout dependency are needed.
|
||||
- Start with [development](../development.md), then read the
|
||||
[agent](../policy/agents.md) policy and applicable
|
||||
[architecture](../policy/architecture.md),
|
||||
[testing](../policy/testing.md),
|
||||
[documentation](../policy/documentation.md),
|
||||
[release](../policy/release.md), and [OSS](../policy/oss.md) policies.
|
||||
Reuse already-read, unchanged policies and preserve unrelated work.
|
||||
- Inspect current files before each stage. Validate and commit each completed
|
||||
unit under the agent policy. Follow later explicit user instructions about
|
||||
commits if they differ.
|
||||
- All Git publication during implementation verification targets disposable
|
||||
local remotes. Implementing this plan does not authorize publishing to
|
||||
PromptKit's actual origin, creating a real release tag, or modifying ReleaseKit.
|
||||
- Keep PromptKit's runtime API and business logic unchanged. The approved Go
|
||||
requirement update and tool dependency are module changes, not runtime
|
||||
ReleaseKit integration.
|
||||
- Retain source-only publication, the main-before-tag workflow, and completion
|
||||
at confirmed tag publication. Hosted pages and CI deployment are outside
|
||||
this adoption. Retire the credential regex without adding a replacement gate.
|
||||
- Use the latest Go installation available in the development environment.
|
||||
Activate it as `go`, set `GOTOOLCHAIN=local`, and use it for tool builds,
|
||||
candidate tests, and examples. At planning time the active local version is
|
||||
`go1.26.8`; derive the version during implementation instead of freezing it
|
||||
in scripts. Do not query `go@latest` or download another toolchain to find it.
|
||||
- Keep dependency preparation separate from offline validation. Reuse successful
|
||||
checks for unchanged content; do not add parallel validators, a persistent
|
||||
validation cache, or additional human release sign-offs.
|
||||
|
||||
## Stage 1 — Declare The Released Tool And Advance The Go Requirement
|
||||
|
||||
**Outcome:** Module metadata selects ReleaseKit as a maintainer tool and records
|
||||
the development environment's current Go requirement.
|
||||
|
||||
**Read:** `go.mod`, `go.sum`, the runbook's
|
||||
[preparation step](../release.md#prepare-the-candidate), and the OSS policy.
|
||||
|
||||
**Changes:**
|
||||
|
||||
1. From the repository root, use the active latest local Go installation:
|
||||
`export GOTOOLCHAIN=local`; capture `go env GOVERSION`.
|
||||
2. Advance the requirement with
|
||||
`go get "go@${release_go_version#go}"`, where `release_go_version` contains
|
||||
that captured value. This is preparation before the resulting candidate
|
||||
commit, not an operation performed inside publication.
|
||||
3. Add the tool with
|
||||
`go get -tool gitea.maximumdirect.net/eric/ReleaseKit/cmd/releasekit@v0.2.0`.
|
||||
Use a Go `tool` declaration, not an artificial runtime import or a
|
||||
`tools.go` workaround.
|
||||
4. Prepare dependencies with `GOTOOLCHAIN=local go mod download`. Review the
|
||||
module and checksum changes; retain necessary tool/transitive dependencies
|
||||
without opportunistic unrelated upgrades.
|
||||
5. Apply the OSS policy according to actual use. This is tool-only use, with
|
||||
no copied ReleaseKit implementation or documentation; that alone requires
|
||||
no new attribution entry. If a necessary existing dependency selection
|
||||
changes, maintain its applicable existing notices in this unit.
|
||||
6. Preserve repository independence: no committed workspace or local
|
||||
filesystem replacement. Do not select a PromptKit release version or write
|
||||
a prospective versioned release note in this stage.
|
||||
|
||||
**Verification:**
|
||||
|
||||
- `GOTOOLCHAIN=local go list -m gitea.maximumdirect.net/eric/ReleaseKit` identifies
|
||||
`v0.2.0`; module metadata declares the intended tool.
|
||||
- Run `GOTOOLCHAIN=local go test -mod=readonly ./...` for the Go/module change.
|
||||
- Inspect `go list -deps .` to confirm the runtime facade has no ReleaseKit
|
||||
import dependency. Review the diff and commit the unit.
|
||||
|
||||
## Stage 2 — Extract The Consumer Check And Declare Shared Validation
|
||||
|
||||
**Outcome:** One focused example checker and one profile express the selected
|
||||
validation without changing the publication entry point yet.
|
||||
|
||||
**Read:** The example-assertion block in `scripts/release-check.sh`, the three
|
||||
maintained examples, the testing policy, and ReleaseKit's profile reference.
|
||||
|
||||
**Changes:**
|
||||
|
||||
1. Create `scripts/check-examples.py`, runnable as
|
||||
`python3 scripts/check-examples.py`. Use Python's standard library, derive
|
||||
the repository root from the script location, and run from that root.
|
||||
2. Move the existing semantic assertions into that checker. Preserve all current
|
||||
expectations: preparation ID/profile/model/message count; execution output,
|
||||
validity, validation status, model and token count; observation attempt/retry
|
||||
counts, usage completeness, and accepted assessment outcome.
|
||||
3. Execute each example once, parse its JSON, propagate compilation/process and
|
||||
assertion failures as nonzero results, and provide useful failure context.
|
||||
Keep the checker narrow; it does not run tests, vet, formatting, links,
|
||||
module inspection, or publication.
|
||||
4. Use the selected local Go installation for example execution. Set native
|
||||
host `GOOS`/`GOARCH` from that installation's `go env GOHOSTOS GOHOSTARCH`
|
||||
for the example children so ambient cross-build settings do not select an
|
||||
unexecutable target. Keep normal native cgo/cache settings.
|
||||
5. Create root `releasekit.json` with these exact selections:
|
||||
|
||||
| Profile field | Value |
|
||||
| --- | --- |
|
||||
| `product` | `"Promptkit"` |
|
||||
| `remote` | `"origin"` |
|
||||
| `validation.go.race` | `true` |
|
||||
| `validation.go.full_vet` | `true` |
|
||||
| `validation.go_format` | `true` |
|
||||
| `validation.markdown` | `{}` |
|
||||
| `validation.module_distribution.workspace_files` | `true` |
|
||||
| `validation.module_distribution.local_replacements` | `true` |
|
||||
|
||||
Set `checks` to one command whose argument vector is
|
||||
`["python3", "./scripts/check-examples.py"]`. Its environment map selects
|
||||
`GOTOOLCHAIN=local`, `GOWORK=off`, `GOFLAGS=-mod=readonly`,
|
||||
`GOPROXY=off`, `GONOPROXY=none`, and `GOSUMDB=off`. These settings apply to
|
||||
the additional check; ReleaseKit owns its own shared Go environment.
|
||||
6. Omit `build`, `delivery`, `expected_push_url`, package-compilation targets,
|
||||
file-size selection, and Markdown boundary enforcement. Accept the upstream
|
||||
default out-of-scope handling for outside-checkout Markdown destinations.
|
||||
7. Add a concise standalone example-check command to the development guide.
|
||||
Keep the existing publication/checker documentation until the cutover.
|
||||
|
||||
**Verification:**
|
||||
|
||||
- Run the new example checker using the offline environment above.
|
||||
- Check profile JSON syntax and the selected fields against the released
|
||||
reference. Detailed API/profile equivalence tests belong upstream.
|
||||
- Review the extracted assertions against the old block, then commit.
|
||||
|
||||
## Stage 3 — Add The Native Tool Bootstrap
|
||||
|
||||
**Outcome:** A small shared invocation script builds and runs the module-selected
|
||||
native executable. Legacy source publication remains active until Stage 6.
|
||||
|
||||
**Read:** `.gitignore`, the new module declaration and profile, and the
|
||||
upstream CLI contract.
|
||||
|
||||
**Changes:**
|
||||
|
||||
1. Create executable POSIX-shell `scripts/releasekit.sh`. Its role is:
|
||||
enter its repository root, build the declared tool, and invoke the native
|
||||
executable with the supplied CLI arguments.
|
||||
2. Use `set -eu`, `GOTOOLCHAIN=local`, `GOWORK=off`, and
|
||||
`GOFLAGS=-mod=readonly`. Build
|
||||
`gitea.maximumdirect.net/eric/ReleaseKit/cmd/releasekit` with
|
||||
`go build -mod=readonly` into `.releasekit/bin/releasekit`.
|
||||
Select the native host `GOOS`/`GOARCH` for that build using the active Go
|
||||
installation's host values.
|
||||
3. Rebuild through Go's normal build cache on each invocation. This ensures the
|
||||
executable uses the active Go compiler and module selection, without a
|
||||
custom cache/version-validation protocol.
|
||||
4. Use `exec` to invoke the built executable and forward `"$@"` unchanged.
|
||||
Delegate command/version parsing, candidate guards, and exit classifications
|
||||
to ReleaseKit. Do not use `go run` for publication.
|
||||
5. Ignore the root `.releasekit/` directory. Do not commit the built tool or
|
||||
describe it as a PromptKit binary deliverable.
|
||||
6. Bootstrap may use ordinary module access if preparation has not populated
|
||||
caches, while readonly mode preserves module files. Candidate validation and
|
||||
examples remain offline. Bootstrap does not edit the Go requirement, fetch
|
||||
Git refs itself, create tags, or add publication guards.
|
||||
7. Add an optional diagnostic `./scripts/releasekit.sh check VERSION` invocation
|
||||
to the current runbook, linked to upstream requirements for a committed
|
||||
candidate. Make clear it is not required before publication.
|
||||
|
||||
**Verification:**
|
||||
|
||||
- Run `sh -n scripts/releasekit.sh`.
|
||||
- Run `./scripts/releasekit.sh version`; inspect the executable with
|
||||
`go version -m` to confirm its recorded Go build version matches the selected
|
||||
installation and its module selection is the released ReleaseKit.
|
||||
- Check that bootstrap leaves `go.mod`/`go.sum` unchanged and the tool output
|
||||
ignored. No real publication is performed. Commit.
|
||||
|
||||
## Stage 4 — Add A Small Successful Publication Fixture
|
||||
|
||||
**Outcome:** A standalone offline integration check protects local bootstrap,
|
||||
profile wiring, and successful source publication.
|
||||
|
||||
**Read:** The production profile/bootstrap, the testing policy, and the
|
||||
upstream source-publication contract.
|
||||
|
||||
**Changes:**
|
||||
|
||||
1. Create `scripts/test-release.py`, invoked explicitly with Python 3 during
|
||||
tooling development. Keep it outside the default Go suite and outside the
|
||||
profile's release checks. It is not a new per-release gate.
|
||||
2. Use standard-library temporary directories and subprocesses with real Git
|
||||
and the released tool. Use a synthetic working repository on `main` and a
|
||||
local bare `origin`; all identities and release versions are fixture data.
|
||||
3. Copy the production bootstrap, profile, and relevant ignore rule into the
|
||||
fixture. Copy the selected `go.mod`/`go.sum` so tool selection follows
|
||||
production metadata without a local replacement.
|
||||
4. Add a tiny formatted Go package and test. The test writes an invocation
|
||||
marker outside the checkout and records `runtime.Version()`. Use small
|
||||
race/non-race build-tag files so the test can prove the selected suite was
|
||||
race-enabled. This fixture never imports or retests PromptKit's full library.
|
||||
5. At the configured example-check path, install a fixture-only Python stand-in
|
||||
that writes an external invocation marker. Keep the real profile command
|
||||
and validation selections unchanged. Stage 2 verifies the real examples;
|
||||
this fixture verifies additional-check wiring.
|
||||
6. Add a simple version-matched release note, commit the fixture, and push its
|
||||
`main` to the local bare remote. Run the copied bootstrap's `publish`
|
||||
command from outside the fixture's repository root to exercise path handling.
|
||||
7. Keep the test invocation offline with prepared module caches,
|
||||
`GOTOOLCHAIN=local`, `GOPROXY=off`, `GONOPROXY=none`, and `GOSUMDB=off`.
|
||||
Format generated Go files before committing them.
|
||||
8. Assert native status 0, exactly one suite marker and one additional-check
|
||||
marker, and equal selected/tool-build/test Go versions. Verify that the
|
||||
local and remote tag are annotated and identify the fixture candidate,
|
||||
with the committed note as annotation. Confirm module bytes are unchanged
|
||||
and the fixture remains clean apart from ignored tool output.
|
||||
|
||||
**Verification:**
|
||||
|
||||
- Run `python3 scripts/test-release.py` after dependency preparation.
|
||||
- Inspect that fixtures and markers use only temporary paths/local remotes.
|
||||
- Do not add upstream's full tag/recovery/checker matrix or test framework.
|
||||
Commit the focused success-path test.
|
||||
|
||||
## Stage 5 — Cover Local Failure Propagation
|
||||
|
||||
**Outcome:** The same fixture demonstrates that failed product validation cannot
|
||||
publish a tag and that native argument failures remain classified.
|
||||
|
||||
**Read:** Stage 4's fixture and ReleaseKit's CLI exit classifications.
|
||||
|
||||
**Changes:**
|
||||
|
||||
1. Extend the fixture stand-in to select failure through a test-owned
|
||||
environment value. In a fresh candidate/version, let shared validation pass
|
||||
and then fail that additional check.
|
||||
2. Assert nonzero native publication status 1, one suite and one additional-check
|
||||
invocation, useful failure context, and no selected tag locally or remotely.
|
||||
Keep the fixture clean and module metadata unchanged.
|
||||
3. Add one malformed/unsupported invocation case that exercises native status 2.
|
||||
Check the classification and a useful diagnostic fragment, not a complete
|
||||
output snapshot.
|
||||
4. Reuse the small fixture setup and production profile. Do not simulate CI,
|
||||
live push errors, uncertain-write reconciliation, hosted delivery, or
|
||||
malicious concurrent mutation; those are upstream responsibilities.
|
||||
5. Preserve cleanup of the temporary repositories and external markers.
|
||||
Failures must not modify the actual PromptKit checkout or its remote.
|
||||
|
||||
**Verification:**
|
||||
|
||||
- Run the completed standalone integration check.
|
||||
- Review coverage for the three risks: successful wiring, failed additional
|
||||
validation, and native usage classification. Commit.
|
||||
|
||||
## Stage 6 — Cut Over Publication And Its Canonical Documentation
|
||||
|
||||
**Outcome:** One publication command uses ReleaseKit; obsolete local validators
|
||||
and their documented gates are retired in the same unit.
|
||||
|
||||
**Read:** `scripts/release.sh`, `scripts/release-check.sh`, the released CLI
|
||||
and recovery guidance, and the affected canonical documentation.
|
||||
|
||||
**Changes:**
|
||||
|
||||
1. Replace `scripts/release.sh` with a thin executable wrapper that delegates to
|
||||
`scripts/releasekit.sh publish`, forwarding supplied arguments through
|
||||
`exec`. Keep the familiar `./scripts/release.sh VERSION` entry point.
|
||||
Add no duplicate argument, branch, remote, note, tag, or status machinery.
|
||||
2. Delete `scripts/release-check.sh`. The shared suite, vet, formatting,
|
||||
Markdown parser, and module checks now belong to ReleaseKit. The example
|
||||
assertions already have their focused owner.
|
||||
3. Remove the credential-pattern gate, clean-candidate diff-whitespace gates,
|
||||
ambient-workspace rejection, blanket vendor-path check, blanket replacement
|
||||
prohibition, mandatory four-heading note validator, and extra annotation
|
||||
commit line. Retain ordinary credential-aware change review and useful
|
||||
development `git diff --check` commands.
|
||||
4. Update `scripts/test-release.py` to copy and invoke the actual
|
||||
`scripts/release.sh` entry point for publication cases. The generic native
|
||||
invocation can continue to own the CLI classification case.
|
||||
5. Update `docs/policy/release.md` locally where needed:
|
||||
shared selections, source-only deliverables, main-before-tag publication,
|
||||
the simpler note convention, native recovery states, and retired gates.
|
||||
Preserve SemVer/compatibility rules, immutable records, catalog exceptions,
|
||||
the Go-update/same-toolchain requirement, and successful-tag-push completion.
|
||||
Preserve upstream provenance/base-policy metadata; update the local date.
|
||||
6. Update `docs/policy/testing.md` to describe selected race/full vet and
|
||||
consumer workflows, with shared machinery upstream. Document the standalone
|
||||
wiring check as focused development validation, not a recurring release
|
||||
requirement or part of default Go tests.
|
||||
7. Rewrite the relevant `docs/release.md` sections around:
|
||||
activate the latest available local Go; update its requirement before the
|
||||
candidate commit; prepare module caches; author the note/footer; retire
|
||||
completed roadmaps; ordinary review/commit; push `main`; run the single
|
||||
publication command. Preparation commands may update module metadata before
|
||||
commit; bootstrap/validation preserve the final candidate.
|
||||
8. Document native statuses 0/1/2/3 and the upstream captured-endpoint recovery
|
||||
model. Link to upstream detail and include a concise usable recovery command.
|
||||
Never resolve uncertainty by deleting a tag before confirming authoritative
|
||||
absence. No CI wait, successful-push read-back, or installation check is added.
|
||||
9. Update `docs/development.md`: remove the old checker command/inventory and
|
||||
scanner reference; retain proportionate tests, formatting, examples and
|
||||
ordinary review for dirty development work. Identify the optional committed
|
||||
candidate diagnostic and the separate tooling integration command.
|
||||
10. Repair links to the removed checker. Keep existing historical release notes,
|
||||
licenses, runtime inventory, and public API documentation unchanged unless
|
||||
a concrete affected reference requires correction. No prospective release
|
||||
note, hosted workflow, or new consumer restriction is part of this unit.
|
||||
|
||||
**Verification:**
|
||||
|
||||
- Run `sh -n` on the two wrappers and the completed integration check using the
|
||||
final publication entry point.
|
||||
- Review the diff for policy/procedure agreement and removal of the listed
|
||||
duplicate gates. Check links and whitespace without running a second complete
|
||||
package suite solely for these documentation edits. Commit the cutover.
|
||||
|
||||
## Stage 7 — Verify The Actual Profile Against The Complete Source Snapshot
|
||||
|
||||
**Outcome:** The assembled adoption is verified without publishing a real
|
||||
PromptKit release.
|
||||
|
||||
**Read:** The final roadmap, profile, wrappers, runbook, and this plan's
|
||||
completion criteria.
|
||||
|
||||
**Work:**
|
||||
|
||||
1. Confirm prior stages are committed and the working checkout is clean.
|
||||
Use the same active local Go installation and prepared module cache.
|
||||
2. Make a disposable local clone of the final committed PromptKit source,
|
||||
checkout `main`, and add/commit only a synthetic unused version's release
|
||||
note there. The note follows the adopted product/version convention and
|
||||
footer paths. Do not add that note to the actual checkout.
|
||||
3. Run the clone's `scripts/releasekit.sh check VERSION` with the real profile
|
||||
and actual example checker. This is the one complete final smoke check:
|
||||
the real race-enabled suite, full vet, formatting, Markdown, committed
|
||||
distribution checks, and three examples. Do not also run the old full
|
||||
checker or another full test/vet/example sequence for that same snapshot.
|
||||
4. Confirm module files remain unchanged, actual example checks succeed,
|
||||
shared Markdown/format checks inspect the final source, and the clone remains
|
||||
clean. This local `check` creates no tag and needs no remote publication.
|
||||
5. If supported upstream checks expose affected formatting or documentation
|
||||
defects, correct those specific issues and commit the changed candidate
|
||||
before repeating the snapshot check. Do not disable the selected validation
|
||||
to make the smoke check pass.
|
||||
6. Audit completion against the roadmap: module tool selection, native/same-Go
|
||||
bootstrap, all six optional validation selections, one local example check,
|
||||
retired validators/gates, accurate runbooks/policies, and successful fixture
|
||||
publication/failure protection. Reuse Stage 6's unchanged integration results.
|
||||
7. Report the implementation commits, checks, and any remaining issues. Update
|
||||
temporary roadmap/plan status to reflect implemented work awaiting review;
|
||||
keep the documents available for the user's review. Release preparation and
|
||||
completed-roadmap retirement remain later maintainer work.
|
||||
|
||||
**Completion criteria:**
|
||||
|
||||
- The final source-only publication command delegates to released ReleaseKit;
|
||||
the committed profile is the single local declaration of selected checks.
|
||||
- Go metadata records the preparation-time requirement; tool build, native
|
||||
validation and examples use the same selected local Go installation.
|
||||
- Profile-selected shared validation and the real consumer examples pass on the
|
||||
complete source snapshot, while fixture failures prevent publication.
|
||||
- No runtime ReleaseKit import, local module replacement, extra release gate,
|
||||
hosted workflow, provider call, real origin push, or real release tag has
|
||||
been introduced.
|
||||
- Canonical docs agree with implemented tooling and preserve the accepted
|
||||
compatibility, catalog, licensing-footer and release-completion policies.
|
||||
|
||||
No significant product decisions remain open. Implementation choices above
|
||||
settle the filenames, bootstrap, profile, validation boundaries, and test
|
||||
strategy needed to carry out the agreed scope.
|
||||
@@ -1,7 +1,7 @@
|
||||
# ReleaseKit Adoption Roadmap
|
||||
|
||||
Status: Adoption scope agreed; implementation has not started.
|
||||
A companion staged implementation plan will define the implementation steps.
|
||||
The [implementation plan](implementation.md) owns the ordered migration steps.
|
||||
|
||||
## Purpose
|
||||
|
||||
@@ -239,5 +239,4 @@ workflow. Source-publication testing requires no provider credentials or
|
||||
live inference.
|
||||
|
||||
The desired reduction is in owned machinery and routine decisions, not a
|
||||
fixed deletion count. The companion implementation plan will divide this
|
||||
migration into appropriately scoped stages.
|
||||
fixed deletion count.
|
||||
|
||||
Reference in New Issue
Block a user