14 KiB
ReleaseKit Adoption Roadmap
Status: Adoption scope for review; implementation has not started. A companion staged implementation plan will define the implementation steps.
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.
Baseline And Available Upstream Support
The current PromptKit baseline is commit
7310ef34a44dae7288db7b281e2a6b7f2c56c4e9. Its implemented
release procedure uses scripts/release.sh for publication
and scripts/release-check.sh for validation. The scripts contain 209 lines
and own publication guards, testing, vet, example assertions, formatting,
Markdown links, module checks, whitespace checks, and a credential regex.
There is no ReleaseKit dependency or hosted delivery workflow.
The earlier adoption assessment is preserved in Git history. This roadmap supersedes its recommendations where the released upstream capabilities change the available choices.
Adopt 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 actual
integration still needs validation during implementation.
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.
Tool output stays outside committed source, and preparation preserves the candidate's module files. 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.
Hosted note-page delivery remains the decision described at the end of this roadmap.
Changes Needed From The Current 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.
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.
The recommended target also retires the mandatory credential regex, subject to Open Decision 2. Ordinary credential-aware change review remains part of development. 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 existing compatibility 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 |
Provide the short executable runbook for tool/dependency preparation, candidate 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
The implementation should demonstrate that PromptKit's profile and entry point select the released tool and expected checks, that the maintained examples still verify meaningful consumer behavior, and that the resulting procedure can validate and publish to a temporary Git remote.
Use a small representative integration fixture for local wiring and failure propagation. ReleaseKit owns the shared validators' and publication machinery's detailed behavioral tests. Avoid duplicating its matrix or recursively running PromptKit's complete suite from an integration test.
Adoption is complete when the implemented release path uses ReleaseKit, the selected shared validators replace local equivalents, the retained example check is integrated, and policies and runbooks describe the actual workflow. Source-publication testing requires no provider credentials or live inference. If hosted delivery is selected, its integration has its own verification and delivery status.
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.
Open Decisions
1. Include Hosted Gitea Release Notes In This Adoption?
Recommendation: Adopt source publication first and leave hosted delivery for a separately selected expansion. This achieves the immediate standardization and maintenance goals. PromptKit currently has no hosted CI; introducing a runner workflow and delivery credentials adds operational scope rather than enabling the shared validation features.
Alternative: Include asynchronous page-only delivery using ReleaseKit's maintained module-selected Woodpecker integration. This follows upstream's broader consumer direction and improves release discoverability with little bespoke implementation. It requires a delivery profile, CI configuration, credentials, and documented delivery retries. The released tag selects the tool for retries, and successful source publication still completes the release independently of page delivery.
2. Retire Or Retain The Credential-Pattern Gate?
Recommendation: Retire the mandatory regex scan and retain ordinary credential-aware change review. Its limited formats and possible matches against synthetic fixtures do not justify preserving a separate local gate merely because ReleaseKit has no equivalent. This simplifies publication without changing the obligation to keep actual credentials out of source.
Alternative: Retain the small existing scan as a focused additional check if its independent automated signal is considered worth its cost and false positives. This catches some recognizable accidentally committed formats but leaves a local validation fragment to maintain and is not comprehensive detection. It does not require a new upstream security subsystem.