245 lines
14 KiB
Markdown
245 lines
14 KiB
Markdown
# 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](../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.
|
|
|
|
## 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](../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.
|
|
|
|
## 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](../release.md) describes the adopted
|
|
workflow rather than these retired mechanics.
|
|
|
|
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.
|
|
|
|
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 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.
|
|
|
|
## 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](../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.
|
|
|
|
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](../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.
|
|
|
|
## 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.
|