14 KiB
ReleaseKit Adoption 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 and release policy. The completed implementation plan is retained in Git history; the current implementation plan covers another feature.
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.
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, testing policy, and agent policy govern the migration; policy changes belong in the implementation alongside the new workflow.
Original Baseline And Adopted Upstream Support
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 describes the adopted
workflow rather than these retired mechanics.
The earlier adoption assessment is preserved in Git history. This roadmap supersedes its recommendations where the released upstream capabilities change the available choices.
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.
The upstream owners of the adopted behavior are:
- ReleaseKit configuration.
- Candidate validation.
- Source publication.
- CLI behavior.
- Module-selected tooling decision.
No further upstream feature work is needed for the proposed source-publication scope.
Target End State
Tool Selection And Local Ownership
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.
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 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.
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 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.
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.
Shared Validation Selection
Select the following capabilities through the ReleaseKit profile:
| 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. |
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.
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.
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 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. 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.
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.
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.