From eae21797f7ccbca7b2b23bc0a184a836e117953f Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Fri, 9 Oct 2026 03:41:56 +0000 Subject: [PATCH] Describe the ReleaseKit upgrade scope --- docs/roadmap/releasekit.md | 301 +++++++++++-------------------------- 1 file changed, 85 insertions(+), 216 deletions(-) diff --git a/docs/roadmap/releasekit.md b/docs/roadmap/releasekit.md index 5939aa8..a9c3db5 100644 --- a/docs/roadmap/releasekit.md +++ b/docs/roadmap/releasekit.md @@ -1,244 +1,113 @@ -# ReleaseKit Adoption Roadmap +# ReleaseKit v0.3.0 Upgrade Roadmap -Status: Implemented and integration-verified (2026-10-08). This completed -roadmap is retained for review until release preparation retires it; current -commands and requirements belong in the [release procedure](../release.md) -and [release policy](../policy/release.md). -The completed [implementation plan](https://gitea.maximumdirect.net/eric/promptkit/src/commit/d5f34642d74a220d3ae61eaeb9f0fb4b0b71a173/docs/roadmap/implementation.md) -is retained in Git history; the current implementation plan covers another feature. +Status: Accepted; implementation pending. ## Purpose -Adopt ReleaseKit's common release workflow and move reusable release -validation and publication mechanics upstream. PromptKit should maintain -product settings, release-note content, and substantive consumer checks, -with little release orchestration of its own. +Upgrade PromptKit's existing ReleaseKit integration to benefit from upstream +validation efficiency and cancellation improvements. Keep reusable release +mechanics upstream and maintain only PromptKit's settings, thin invocation +wrappers, and product-specific checks locally. -Changes to existing release mechanics are an acceptable trade-off for -standardization and lower maintenance. Prefer supported upstream conventions -over preserving incidental local behavior. The -[release policy](../policy/release.md), -[testing policy](../policy/testing.md), and -[agent policy](../policy/agents.md) govern the migration; policy changes belong -in the implementation alongside the new workflow. +This is a focused tooling upgrade, not another release-process migration. +The [release policy](../policy/release.md) and +[release procedure](../release.md) continue to own PromptKit's release +requirements and workflow. A separate implementation plan will own staged work. -## Original Baseline And Adopted Upstream Support +## Current Baseline And Reviewed Upstream -The original PromptKit baseline was commit -`7310ef34a44dae7288db7b281e2a6b7f2c56c4e9`. At that baseline, publication used -`scripts/release.sh` and validation used `scripts/release-check.sh`. Those -scripts contained 209 lines and owned publication guards, testing, vet, example -assertions, formatting, Markdown links, module checks, whitespace checks, and -a credential regex. There was no ReleaseKit dependency or hosted delivery -workflow. The current [release procedure](../release.md) describes the adopted -workflow rather than these retired mechanics. +PromptKit baseline: `ea6c7d5f0f2c008d9c57c8ac25fbd6faa18b5fc6`. -The earlier -[adoption assessment](https://gitea.maximumdirect.net/eric/promptkit/src/commit/7310ef34a44dae7288db7b281e2a6b7f2c56c4e9/docs/roadmap/releasekit.md) -is preserved in Git history. This roadmap supersedes its recommendations -where the released upstream capabilities change the available choices. +- `go.mod` declares the ReleaseKit CLI as a Go tool dependency, selecting + `gitea.maximumdirect.net/eric/ReleaseKit v0.2.0`. PromptKit already declares + `go 1.26.0`. +- `scripts/releasekit.sh` builds the module-selected native executable with the + active local Go toolchain; `scripts/release.sh` delegates publication to it. +- `releasekit.json` selects shared validation and the maintained offline + consumer-example check. PromptKit publishes source-only tags. +- `scripts/test-release.py` exercises local wiring in disposable repositories, + but its executable-metadata assertion hard-codes ReleaseKit `v0.2.0`. +- The runbook links to v0.2.0 upstream documentation. The completed original + [adoption roadmap](https://gitea.maximumdirect.net/eric/promptkit/src/commit/ea6c7d5f0f2c008d9c57c8ac25fbd6faa18b5fc6/docs/roadmap/releasekit.md) + remains available in Git history. -The adoption selected the published ReleaseKit `v0.2.0` baseline, commit -`e030794969fb7787e647a90bbc4eb81bd0610f07`. Its public API and profile provide -all four primary requested capabilities and module-distribution checks. -The reviewed release's full offline test suite passed. PromptKit's integration -was subsequently validated through the completed implementation plan and the -adoption review recorded in [remediation.md](remediation.md#earlier-releasekit-adoption-review). +The reviewed upstream release is `v0.3.0`, commit +`e43df4416e0ed987349b2ea04a2c68c25e552772`. Its local tag was checked against +the upstream remote. The +[release notes](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.3.0/docs/releases/v0.3.0.md) +describe reduced Git subprocess work, lower validation retention, fewer command +output copies, and improved cancellation during reader shutdown. Public +signatures, CLI commands, and profile schema are unchanged. The minimum Go +version rises to 1.26.0; PromptKit already satisfies it. -The upstream owners of the adopted behavior are: - -- [ReleaseKit configuration](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.2.0/docs/config.md). -- [Candidate validation](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.2.0/docs/consumers/check.md). -- [Source publication](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.2.0/docs/consumers/publish.md). -- [CLI behavior](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.2.0/docs/cli.md). -- [Module-selected tooling decision](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.2.0/docs/adr/0004-module-selected-tooling.md). - -No further upstream feature work is needed for the proposed source-publication -scope. +Race-enabled tests passed for the reviewed upstream Git, validation, Go-tool, +process, and runtime-version packages. This evidence supports adoption; it does +not replace verification of PromptKit's upgraded integration. Upstream delivery +and runtime-version improvements require no new PromptKit integration. ## Target End State -### Tool Selection And Local Ownership +### Module-Selected Tooling -PromptKit declares `gitea.maximumdirect.net/eric/ReleaseKit/cmd/releasekit` -as a Go tool dependency, initially selecting ReleaseKit `v0.2.0` through -its module configuration. That selection is the version source for local -release tooling and any later module-based delivery integration. +The existing tool declaration selects ReleaseKit v0.3.0 through PromptKit's +module graph. Module and checksum changes are committed, with no local +filesystem replacement or dependency on the sibling checkout. -A small `releasekit.json` profile declares product identity, the publication -remote, shared validation choices, and the PromptKit-specific example check. -Use `Promptkit` as the product value to match existing release-note titles, -with `main` and `origin` as the release branch and remote. +The current wrappers retain native command exit statuses and build the tool +using the same active local Go installation used for candidate validation. +There is no ReleaseKit runtime import in the PromptKit library. This upgrade +does not require raising PromptKit's existing Go minimum. -The existing publication entry point becomes a thin wrapper that prepares -and invokes the module-selected native ReleaseKit executable. Native -publication exit classifications remain available, including an uncertain -push result. Tool bootstrap and dependency preparation precede offline -candidate validation. The wrapper's responsibility is tool invocation; -ReleaseKit owns candidate guards, validation coordination, tags, and recovery. +### Existing Workflow And Validation -Release preparation records the initial stable release of the latest locally -available Go series as PromptKit's minimum requirement, retaining a higher patch -minimum where needed by a dependency or a specific correctness fix. The -[runbook preparation step](../release.md#prepare-the-candidate) makes that -series' latest locally available patch active before committing the candidate. -The module minimum and build toolchain are separate: for example, `go 1.26.0` -can be built and validated with Go 1.26.8. Use the same local Go version -to build ReleaseKit and run PromptKit's release validation, including the -consumer examples. Local tooling uses that selected installation rather than -an executable previously built with a different Go version or an automatically -downloaded toolchain. This also aligns ReleaseKit's built-in formatter with -the Go toolchain selected for the release. +Keep the current release profile and selected gates unchanged. Continue the +main-before-tag publication workflow and successful-push completion point, +without CI or module-availability waits. Existing release-note and recovery +requirements remain governed by the canonical policy and runbook. -Tool output stays outside committed source, and preparation preserves the -committed candidate's module files after the preparation-time Go update. -The library's supported runtime API and execution logic need no changes. -Tool declarations affect the module graph without -adding a ReleaseKit runtime import or a PromptKit release-orchestration package. +The upstream performance improvements apply through the dependency upgrade. +No local reimplementation, benchmark threshold, extra release gate, hosted +delivery integration, or additional profile capability is part of this scope. -### Shared Validation Selection +### Maintainable Wiring Verification -Select the following capabilities through the ReleaseKit profile: +The disposable release fixture verifies that its native executable was built +from the ReleaseKit version selected by the candidate module, rather than from +a second hard-coded version. Preserve its existing same-Go, publication, +validation-failure, usage-status, and unchanged-module-metadata coverage. -| Capability | Target selection | Purpose | -| --- | --- | --- | -| Full Go suite | Upstream standard suite, once | Validate the committed candidate through the common workflow. | -| Race detector | `validation.go.race: true` | Preserve protection for PromptKit's concurrent execution and capacity management. | -| Full vet | `validation.go.full_vet: true` | Preserve full static analysis while ReleaseKit disables overlapping test-time vet. | -| Go formatting | `validation.go_format: true` | Replace the local formatting loop with upstream committed-source inspection. | -| Offline Markdown links | `validation.markdown: {}` | Replace the local parser with upstream destination and fragment validation. | -| Committed workspace files | `validation.module_distribution.workspace_files: true` | Enforce the established committed-workspace boundary. | -| Filesystem replacements | `validation.module_distribution.local_replacements: true` | Enforce the established local-filesystem dependency boundary. | +Keep this verification focused on PromptKit's wiring. ReleaseKit owns tests of +its internal batching, parsing, cancellation, and publication implementation. -Accept the supported upstream behavior and diagnostics for these selections. -In particular, Markdown links outside the checkout use the default -out-of-scope handling; versioned module replacements are permitted. Shared -checks examine the captured committed source, including applicable nested -paths, rather than implementing a second local interpretation. +## Changes Needed From The Baseline -Leave package-compilation targets, file-size limits, and the exact push-URL -expectation unselected. No concrete additional requirement has been identified -for them. Binary build settings likewise remain absent for this source-only -library. Future needs can be evaluated through the normal policy process. +- **`go.mod` and `go.sum`:** upgrade the existing ReleaseKit tool dependency to + v0.3.0 and reconcile module metadata. Review resulting dependency selections; + upstream's own dependency versions are unchanged from v0.2.0. +- **`scripts/test-release.py`:** derive the expected ReleaseKit version from + the selected candidate module and use it in the build-metadata assertion and + diagnostics. Remove the duplicate v0.2.0 expectation. +- **`docs/release.md`:** advance current candidate-check and failure-recovery + links to the adopted v0.3.0 documentation. Preserve the existing procedure. +- **Notices, where applicable:** review selected upstream licensing and any + incorporated material under the [OSS policy](../policy/oss.md). Update only + notices warranted by actual use; tool use alone does not require a new + attribution entry. Preserve historical release records. -### PromptKit-Specific Checks - -Retain one focused additional check that executes the maintained preparation, -execution, and observation examples and verifies their semantic results. -Their expected prompt, output, validation, usage, and retry behavior belongs -to PromptKit. - -This check uses the intended module and local Go context and remains offline. -ReleaseKit runs it after shared validation. It does not repeat the full -suite, vet, formatting, Markdown, or module-distribution checks. - -Ordinary development continues to support validation of uncommitted work -through focused tests, formatting, example execution, and change review. -ReleaseKit's committed-candidate operations are release tools, not a new -requirement to commit before ordinary development validation. - -### Publication, Release Notes, And Recovery - -Retain the main-before-tag workflow: prepare and commit the candidate, push -`main` to `origin`, and run one publication command. Adopt ReleaseKit's -standard guards, committed-note capture, annotated tag, and explicit tag -publication. Successful publication completes the source release. - -Candidate preparation continues to include completed-roadmap retirement and -ordinary change review under the project policies. These remain preparation -work, with no added publication sign-off or CI wait. - -Adopt the upstream note convention: a version-matched committed Markdown note -with a product/version title, a concise summary, and relevant compatibility -or upgrade guidance. Remove enforcement of the four local section names. -Preserve the licensing footer required by the -[OSS policy](../policy/oss.md#discoverability) and link to canonical contracts -where useful. The note itself supplies the annotation; the extra -`Validated commit` annotation line is unnecessary. - -Recovery uses ReleaseKit's reported state and captured publication endpoint. -The maintainer runbook explains failed and uncertain outcomes and links to -the upstream recovery contract. Published tags and historical notes retain -their contents. CI, hosted delivery, and module availability are separate -from successful source publication. - -This adoption covers source publication. Hosted note-page delivery is left -for a separately selected expansion; PromptKit currently has no hosted CI, -and delivery would add workflow and credential provisioning beyond the -immediate standardization scope. - -## Adoption Scope From The Original Baseline - -### Replace Local Release Mechanics - -Add the tool declaration and selected dependency to `go.mod`, with applicable -checksum updates, and introduce the small release profile. Replace local -publication mechanics in `scripts/release.sh` with native tool invocation. - -Carry the runbook's preparation-time Go update into the adopted workflow. -Build the selected ReleaseKit module with that same local toolchain before -validating the committed candidate. Record the resulting minimum Go version -and relevant compatibility impact when preparing the PromptKit release note. -Tool bootstrap preserves the module files already committed for that release. - -Extract the three example assertions into the focused additional check. -Retire the generic `scripts/release-check.sh` implementation rather than -maintaining parallel shared validators solely for development. - -Remove local version, candidate, remote, note-heading, tag, formatting, -Markdown, and module-validation implementations that ReleaseKit replaces. -Remove the release-only diff-whitespace checks: on a clean candidate they -have no changes to inspect. Ordinary development keeps useful -`git diff --check` validation. - -Remove rejection of an ambient active workspace and the blanket vendor-path -check. Adopt ReleaseKit's controlled test context, and use its committed -workspace/local-replacement selections for the established -[repository-independence requirement](../policy/architecture.md#repository-independence). -The current blanket rejection of all replacement directives gives way to -that more precise upstream check. - -Retire the mandatory credential regex. Its limited formats and possible -matches against synthetic fixtures do not justify keeping a separate local -release gate. Ordinary credential-aware change review remains part of -development, including the obligation to keep actual credentials out of -source. No replacement scanner is required for adoption. - -### Align Policy And Documentation - -Update the affected canonical owners when the implementation lands: - -| File | Required alignment | -| --- | --- | -| `docs/policy/release.md` | Describe the shared validation selections, simpler note convention, adopted publication/recovery model, retired gates, and selected deliverables. Preserve the Go-update/same-toolchain requirement, existing compatibility policy, and catalog-profile policy. | -| `docs/policy/testing.md` | Route release validation through ReleaseKit while retaining race, full vet, and the three consumer workflows. Distinguish ordinary development checks from committed-candidate validation. | -| `docs/release.md` | Preserve the preparation-time series-based Go minimum and latest-local-patch selection; document building ReleaseKit with that same toolchain, dependency preparation, one publication command, and upstream recovery. | -| `docs/development.md` | Replace the old checker inventory and prerequisites with current tool ownership and focused development commands. | -| `docs/oss/attribution.md` and related notices, if applicable | Apply the OSS policy to the selected tooling and any copied or adapted material according to actual use and distribution. Tool use alone is not a blanket attribution requirement. | - -Repair affected incoming links as old scripts are retired. Keep exact upstream -CLI/profile contracts in their upstream owners and PromptKit's selected -release policy in its own canonical documents. The architecture policy's -existing committed-workspace and local-replacement rule remains the relevant -local requirement. - -When preparing the eventual PromptKit release, describe the operational -migration in its release note. This roadmap does not itself select or publish -that version or retrofit past release records. +The existing wrappers and `releasekit.json` need no intended changes. Update +other current documentation only where the upgrade makes it inaccurate; do not +rewrite historical references merely because they identify an earlier release. ## Verification And Completion -Adoption is complete. The module-selected tool and profile replaced the local -shared validators and publication mechanics, while the three example assertions -remain one PromptKit-specific check. The policy and runbook describe the adopted -workflow; no hosted delivery integration was added. +Prepare dependency caches before offline verification. Confirm that the +module-selected native tool builds with the active compatible local Go +installation. Run `python3 scripts/test-release.py` to exercise publication +and failure cases exclusively against disposable local repositories. Review +the module diff and updated documentation links, and use ordinary PromptKit +validation proportionate to the dependency change. -The completed plan and adoption review recorded successful offline candidate -validation and a disposable publication fixture covering annotated publication, -validation failure propagation, native usage-error classification, same-Go -tool bootstrap, and unchanged module metadata. No real publication or provider -access was used for that verification. ReleaseKit owns detailed shared-validator -and publication tests; PromptKit's fixture protects its local wiring. - -The desired reduction is in owned machinery and routine decisions, not a -fixed deletion count. +Completion means v0.3.0 is selected, wiring verification passes without a +duplicated version pin, and current documentation agrees with the adopted +tool. No real tag publication is part of implementation verification. Future +PromptKit release preparation remains a separate task under the runbook.