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

Describe the ReleaseKit upgrade scope

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-09 03:41:56 +00:00
parent ea6c7d5f0f
commit eae21797f7
1 changed files with 85 additions and 216 deletions
Download Patch File Download Diff File Expand all files Collapse all files

301
docs/roadmap/releasekit.md
View File

@@ -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.