promptkit/docs/roadmap/releasekit.md

ReleaseKit v0.3.0 Upgrade Roadmap

Status: Accepted; implementation pending.

Purpose

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.

This is a focused tooling upgrade, not another release-process migration. The release policy and release procedure continue to own PromptKit's release requirements and workflow. A separate implementation plan will own staged work.

Current Baseline And Reviewed Upstream

PromptKit baseline: ea6c7d5f0f2c008d9c57c8ac25fbd6faa18b5fc6.

• 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 remains available in Git history.

The reviewed upstream release is v0.3.0, commit e43df4416e0ed987349b2ea04a2c68c25e552772. Its local tag was checked against the upstream remote. The release notes 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.

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

Module-Selected Tooling

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.

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.

Existing Workflow And Validation

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.

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.

Maintainable Wiring Verification

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.

Keep this verification focused on PromptKit's wiring. ReleaseKit owns tests of its internal batching, parsing, cancellation, and publication implementation.

Changes Needed From The Baseline

• 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. Update only notices warranted by actual use; tool use alone does not require a new attribution entry. Preserve historical 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

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.

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.