Define the ReleaseKit adoption roadmap
This commit is contained in:
@@ -1,276 +1,253 @@
|
||||
# ReleaseKit Adoption Assessment
|
||||
# ReleaseKit Adoption Roadmap
|
||||
|
||||
Status: Recommendations for review. Release tooling and adopted policies have
|
||||
not changed. This assessment is the basis for a later feature roadmap and
|
||||
implementation plan.
|
||||
Status: Adoption scope for review; implementation has not started.
|
||||
A companion staged implementation plan will define the implementation steps.
|
||||
|
||||
## Purpose And Evaluation Standard
|
||||
## Purpose
|
||||
|
||||
Adopt ReleaseKit to standardize PromptKit's release process and reduce the
|
||||
amount and complexity of release code maintained here. Prefer the shared
|
||||
workflow over reproducing every existing local behavior. Retain local checks
|
||||
where they protect a substantive project requirement; propose broadly useful
|
||||
validation upstream where doing so saves continuing maintenance.
|
||||
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 release mechanics are acceptable. Their value should be assessed
|
||||
against the [release policy](../policy/release.md),
|
||||
[testing policy](../policy/testing.md), and the user's preference for few,
|
||||
automated, nonredundant gates. Existing local release checks are evidence to
|
||||
evaluate, rather than a requirement to preserve them all.
|
||||
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 document recommends future changes. The current
|
||||
[release procedure](../release.md) remains authoritative until adoption lands.
|
||||
## Baseline And Available Upstream Support
|
||||
|
||||
## Reviewed Baseline
|
||||
The current PromptKit baseline is commit
|
||||
`7310ef34a44dae7288db7b281e2a6b7f2c56c4e9`. Its implemented
|
||||
[release procedure](../release.md) 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.
|
||||
|
||||
Assessment date: 2026-10-07.
|
||||
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.
|
||||
|
||||
- PromptKit: commit `4b8169da286917fde7875425bb32b799b12c6af3`, with a clean
|
||||
worktree before this assessment. Its release scripts contain 209 lines:
|
||||
57 in [publication](../../scripts/release.sh) and 152 in
|
||||
[validation](../../scripts/release-check.sh).
|
||||
- ReleaseKit: published `v0.1.0`, commit
|
||||
`5e60fe3113c69f95c42fbbe32a8ca4b51f5b83c1`. The local checkout and upstream
|
||||
`main` match the tag's peeled commit. See its
|
||||
[configuration reference](https://gitea.maximumdirect.net/eric/ReleaseKit/src/commit/5e60fe3113c69f95c42fbbe32a8ca4b51f5b83c1/docs/config.md),
|
||||
[publication guide](https://gitea.maximumdirect.net/eric/ReleaseKit/src/commit/5e60fe3113c69f95c42fbbe32a8ca4b51f5b83c1/docs/consumers/publish.md),
|
||||
and [CLI contract](https://gitea.maximumdirect.net/eric/ReleaseKit/src/commit/5e60fe3113c69f95c42fbbe32a8ca4b51f5b83c1/docs/cli.md).
|
||||
- The preceding review ran ReleaseKit's offline Go suite successfully. Its
|
||||
tests use local Git remotes and HTTP fixtures for publication and delivery;
|
||||
this is not evidence of a live PromptKit integration or deployed delivery
|
||||
workflow. No candidate was published as part of either review.
|
||||
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 assessment examined both release scripts, their owning documentation,
|
||||
ReleaseKit's candidate and publication behavior, additional-check execution,
|
||||
and its controlled Go environment. Installed `go help test` confirms that
|
||||
ordinary `go test` includes a subset of vet's default analyses.
|
||||
The upstream owners of the adopted behavior are:
|
||||
|
||||
## Overall Fit
|
||||
- [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).
|
||||
|
||||
ReleaseKit already owns stable-version parsing, committed release-note
|
||||
capture, a clean candidate on `main`, unused local and authoritative remote
|
||||
tags, exact candidate identity, annotated-tag creation, publication, and
|
||||
bounded reconciliation after a failed push. PromptKit already uses the same
|
||||
main-before-tag publication model. ReleaseKit can replace those mechanics
|
||||
without a PromptKit-owned orchestration package.
|
||||
No further upstream feature work is needed for the proposed source-publication
|
||||
scope.
|
||||
|
||||
Its standard candidate suite is
|
||||
`go test -mod=readonly -count=1 ./...`. It uses the available compatible local
|
||||
Go toolchain, disables workspace discovery and module/toolchain downloads for
|
||||
that run, and controls settings that could change the selected tests or host
|
||||
target. Dependency and tool installation belong to preparation. Additional
|
||||
check commands are separate children; they do not automatically inherit that
|
||||
entire controlled Go environment.
|
||||
## Target End State
|
||||
|
||||
Successful source publication remains the completion point. The native CLI
|
||||
also reports known failures, conflicts, and uncertain pushes. PromptKit can
|
||||
use that recovery model directly, including querying the captured publication
|
||||
endpoint when needed. Neither CI success nor consumer installation becomes a
|
||||
release gate.
|
||||
### Tool Selection And Local Ownership
|
||||
|
||||
## Assessment Of Existing Checks
|
||||
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.
|
||||
|
||||
| Current check or responsibility | Recommendation | Reason and ownership |
|
||||
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 |
|
||||
| --- | --- | --- |
|
||||
| Stable SemVer, clean `main`, unused version, synchronized authoritative branch, and candidate rechecks | Adopt ReleaseKit. | These are shared publication mechanics, already implemented and tested upstream. Remove the local equivalents. |
|
||||
| Annotated tag, release-note annotation, and explicit tag-only push | Adopt ReleaseKit. | Use the committed note as the annotation. The extra `Validated commit` annotation line is unnecessary: the tag already identifies that commit. |
|
||||
| Failed or ambiguous push recovery | Adopt ReleaseKit. | Its bounded reconciliation and reported endpoint replace local recovery mechanics. Retain a short maintainer runbook linked to the upstream contract. |
|
||||
| Full Go test suite | Adopt the shared standard suite once. | Remove the suite invocation from additional checks. A separate `check` invocation before `publish` is diagnostic, not a required second pass. |
|
||||
| Race detector | Seek a shared race-enabled standard-suite variant; resolve Open Question 1. | PromptKit has real concurrent execution and capacity management. Race detection offers distinct protection, but the current upstream suite cannot enable it. Do not attach a second complete test run just to preserve the old command. |
|
||||
| Explicit `go vet ./...` | Retain as a configured command pending Open Question 2. | Ordinary `go test` runs only a subset of vet analyses. Full vet is not wholly redundant, although part of its work overlaps. Its invocation needs no custom local implementation. |
|
||||
| Three offline consumer examples with semantic JSON assertions | Retain locally as a focused additional check. | Expected preparation, execution, retry, validation, and usage results are PromptKit-specific. Preserve these assembled consumer workflows without moving their expected values into ReleaseKit. |
|
||||
| Tracked Go formatting | Propose shared upstream support. | Enumerating source files, invoking `gofmt`, and reporting unformatted files are reusable mechanics. Select this check for PromptKit without maintaining its shell loop here. |
|
||||
| Local Markdown paths and heading fragments | Propose shared upstream support. | This is the largest generic block in the checker. Offline broken-link detection protects documentation consumers across repositories. Replace the local parser with supported upstream behavior. |
|
||||
| Rejection of an ambient active Go workspace | Remove this release gate. | ReleaseKit already runs its standard suite with workspace discovery disabled. Apply suitable settings to additional Go commands as well; an unrelated active workspace need not prevent release. |
|
||||
| Tracked `go.work` and `go.work.sum` | Retain the project rule through a small additional check. | The [architecture policy](../policy/architecture.md#repository-independence) expressly keeps workspace files out of PromptKit's committed source. Disabling discovery does not enforce that distribution rule. |
|
||||
| Blanket rejection of every `replace` directive | Narrow to the established project requirement. | Architecture prohibits local filesystem replacements. A versioned module replacement is different; the current blanket check is broader than that stated requirement. Do not export the blanket ban as a shared standard. |
|
||||
| Rejection whenever a `vendor` path exists | Remove the blanket release gate. | The architecture policy does not establish this prohibition. ReleaseKit's standard `-mod=readonly` run avoids automatic vendor selection; a local ignored directory need not block it. Review any intentional distribution change through ordinary development. |
|
||||
| `git diff --check` and its staged counterpart | Keep in ordinary development; remove as release gates. | A clean, committed release candidate has no staged or unstaged diff. These commands add no source-whitespace protection at that point. A new historical or whole-tree whitespace audit would be a different check, not something to add implicitly. |
|
||||
| Fixed credential-pattern scan | Recommend retiring the mandatory release gate; resolve Open Question 4. | The small regex catches some recognizable formats but is incomplete and can match synthetic data. Ordinary credential-aware change review already applies. A broader shared scanner requires its own demonstrated benefit. |
|
||||
| Exact title plus mandatory Summary, Compatibility, Upgrade, and Changes headings | Adopt ReleaseKit's note convention. | Retain the substantive summary and relevant compatibility/upgrade guidance, but remove the extra structure validator. Section names are an editorial choice. Historical notes remain untouched. |
|
||||
| Licensing footer and canonical documentation updates | Retain as preparation under the OSS/documentation policies. | ReleaseKit preserves the captured note, including its footer. This does not call for URL probes, a recurring attribution audit, or another publication sign-off. |
|
||||
| Completed-roadmap retirement | Retain as preparation housekeeping. | Determining whether feature work is complete is project-specific. It does not justify a generic automatic gate or a new human approval step. |
|
||||
| Separate builds, binary targets, provider probes, CI/module-availability waits | Keep absent from source publication. | PromptKit has no binary deliverables or live inference requirement for releases. ReleaseKit supports source-only publication. Hosted note-page delivery is considered separately below. |
|
||||
| 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. |
|
||||
|
||||
The module-file checks should express the selected requirement accurately.
|
||||
Workspace-file and local-replacement rules can share reusable upstream
|
||||
mechanics if there is wider demand, but their policy is not universal to Go
|
||||
applications. Keeping a small local check is preferable to building a broad
|
||||
configuration framework solely to eliminate a few lines.
|
||||
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.
|
||||
|
||||
## Recommended Upstream Work
|
||||
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.
|
||||
|
||||
### Shared Source And Documentation Checks
|
||||
### PromptKit-Specific Checks
|
||||
|
||||
The strongest immediate requests are reusable Go formatting and local
|
||||
Markdown-link checks, available through the shared tooling rather than merely
|
||||
through a Go helper that PromptKit must wrap in its own executable.
|
||||
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.
|
||||
|
||||
The consumer needs are straightforward: inspect the selected repository's
|
||||
tracked source, report actionable failures, and perform offline checks without
|
||||
rewriting files. Markdown checking should cover local paths and supported
|
||||
heading fragments while excluding external URL availability checks. Let
|
||||
ReleaseKit establish its supported Markdown conventions; PromptKit need not
|
||||
preserve its exact regex parser, anchor algorithm, or blanket rejection of
|
||||
links outside the repository as universal policy.
|
||||
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.
|
||||
|
||||
Propose the capabilities and rationale upstream, leaving API and internal
|
||||
implementation design to ReleaseKit. Its routine-release priorities should
|
||||
guide whether these checks become shared defaults or optional selections.
|
||||
Either approach can reduce PromptKit-owned code. PromptKit need not prescribe
|
||||
mandatory checks for every unrelated consumer.
|
||||
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.
|
||||
|
||||
### One Standard Suite With Useful Go Validation
|
||||
### Publication, Release Notes, And Recovery
|
||||
|
||||
Race-enabled execution is a credible upstream request for concurrent Go
|
||||
projects. Full vet within the same standard test operation is another useful
|
||||
candidate. The desired benefit is one complete suite execution with the
|
||||
selected analysis, rather than duplicate test runs or custom per-project test
|
||||
orchestration.
|
||||
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.
|
||||
|
||||
ReleaseKit currently ignores ambient `GOFLAGS`, so setting that variable is
|
||||
not a supported way to alter its suite. Do not work around the standard by
|
||||
trying to filter or neutralize its mandatory tests. Request a small supported
|
||||
capability if these choices remain release requirements. An arbitrary
|
||||
replacement validation command is unnecessary for PromptKit's use case.
|
||||
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.
|
||||
|
||||
These enhancements are not prerequisites for adopting publication. Their
|
||||
acceptance affects the final validation selection, as described under Open
|
||||
Questions. Shared formatting and link checks can also follow initial adoption;
|
||||
until they are available, retain a transitional local implementation only for
|
||||
checks selected to continue.
|
||||
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.
|
||||
|
||||
### Work Not Recommended For Upstreaming Now
|
||||
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.
|
||||
|
||||
Do not propose PromptKit's four note headings, example output values,
|
||||
completed-roadmap judgments, or architecture-specific module restrictions as
|
||||
ReleaseKit defaults. There is also no value in upstreaming the current
|
||||
clean-candidate diff-whitespace checks. The narrow credential regex is not a
|
||||
sufficient basis for a shared security-check subsystem.
|
||||
Hosted note-page delivery remains the decision described at the end of this
|
||||
roadmap.
|
||||
|
||||
## Recommended Adoption Shape
|
||||
## Changes Needed From The Current Baseline
|
||||
|
||||
Use ReleaseKit's pinned native executable as maintainer tooling. A small
|
||||
`releasekit.json` profile supplies product identity, remote selection where
|
||||
needed, and additional checks. A thin repository entry point invokes the tool
|
||||
and preserves its native exit status; direct `go run` publication loses the
|
||||
distinction between ordinary failure and an uncertain push.
|
||||
### Replace Local Release Mechanics
|
||||
|
||||
This needs no PromptKit runtime import, `buildinfo` integration, or public API
|
||||
change. Prefer a separately installed pinned tool over adding release
|
||||
orchestration to the consumer library's dependency graph. Use a released
|
||||
version and documented preparation rather than a sibling-checkout dependency
|
||||
or local `replace` directive.
|
||||
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.
|
||||
|
||||
PromptKit should own only its product facts, release-note content, substantive
|
||||
compatibility choices, and focused additional checks. The selected example,
|
||||
vet, and module checks should use the intended Go toolchain/module context;
|
||||
dependency preparation precedes their offline execution. Keep generic
|
||||
publication guards and recovery tests upstream, with a small local integration
|
||||
check for the actual profile and entry point when adoption is implemented.
|
||||
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.
|
||||
|
||||
Hosted note pages are supported independently of publication. The ReleaseKit
|
||||
product roadmap favors pages for source-only consumers, but its implemented
|
||||
`publish` operation does not require delivery configuration or credentials.
|
||||
Open Question 3 distinguishes adopting that additional channel from adopting
|
||||
source publication.
|
||||
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.
|
||||
|
||||
## Local Changes Needed When Adoption Is Approved
|
||||
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.
|
||||
|
||||
| Affected material | Proposed change |
|
||||
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 |
|
||||
| --- | --- |
|
||||
| `scripts/release.sh` | Replace local orchestration with native ReleaseKit invocation. Preserve one publication entry point. |
|
||||
| `scripts/release-check.sh` | Remove shared-suite execution and retired gates. Move the retained example assertions and module checks into focused additional checks; use upstream generic checks when available. Decide whether a standalone development command still provides value. |
|
||||
| `releasekit.json` and tool preparation guidance | Introduce a small profile and a selected released tool version. Build/delivery settings depend on the chosen deliverables. |
|
||||
| `docs/policy/release.md` | Adopt shared validation, note structure, and recovery behavior; preserve source/tag integrity, compatibility policy, catalog exceptions, and the no-CI-wait completion rule. Record any selected delivery channel. |
|
||||
| `docs/policy/testing.md` | Update the release-candidate validation description consistently with the selected race/vet approach and retained consumer workflows. |
|
||||
| `docs/release.md` | Document preparation, the single publication command, ReleaseKit failure states, and recovery. Link to upstream contracts rather than recreating them. |
|
||||
| `docs/development.md` | Replace the current script inventory and prerequisites with the implemented tool/check ownership and proportionate development validation. |
|
||||
| `docs/policy/architecture.md` | Preserve the explicit committed-workspace/local-replacement boundary. Only adjust text if adoption actually changes that deliberate project decision. |
|
||||
| Release notes and licensing material | Describe adopted operational changes in the next appropriate release note. Preserve the OSS footer. Tool use alone requires no new attribution entry; assess any copied/adapted implementation or documentation under the [OSS policy](../policy/oss.md). |
|
||||
| `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. |
|
||||
|
||||
These are proposed changes, not permission to update unrelated policies or
|
||||
distribution channels during this assessment. A later implementation plan
|
||||
should use the selected released upstream contracts and resolved decisions.
|
||||
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.
|
||||
|
||||
## Expected Benefit And Validation
|
||||
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 immediate benefit is eliminating most of the 57-line publication script
|
||||
and moving its consequential Git behavior and recovery maintenance upstream.
|
||||
Most of the remaining 152 lines are validation, including a large generic
|
||||
Markdown checker. Shared checks, removal of ineffective gates, and simpler
|
||||
note rules can remove substantially more. Exact savings depend on upstream
|
||||
capabilities and the selected validation policy; no deletion quota is needed.
|
||||
## Verification And Completion
|
||||
|
||||
The resulting local surface should be a tool invocation, product settings,
|
||||
and small project-specific checks. Validate those through a representative
|
||||
offline integration using a temporary Git remote, not by reimplementing or
|
||||
retesting ReleaseKit's entire publication matrix. Generic checks receive their
|
||||
behavioral coverage upstream; local tests cover meaningful wiring and
|
||||
PromptKit-specific expectations. Live hosted delivery validation is relevant
|
||||
only if that channel is selected, and never delays source-release 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.
|
||||
|
||||
## Open Questions
|
||||
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.
|
||||
|
||||
### 1. Should Race Detection Remain A Release-Candidate Gate?
|
||||
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.
|
||||
|
||||
**Recommendation:** Seek supported upstream race-enabled standard-suite
|
||||
execution and select it for PromptKit if accepted. Concurrency is substantive
|
||||
library behavior, so this protects a real failure class while retaining one
|
||||
suite run. This is a capability request, not a requirement to preserve our
|
||||
exact existing shell command or to enable race testing for every consumer.
|
||||
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.
|
||||
|
||||
**Alternative:** Adopt the current ordinary ReleaseKit suite and use race
|
||||
testing during concurrency-related development. This provides immediate
|
||||
standardization and avoids an upstream option or additional release cost, but
|
||||
removes a last check for races introduced outside explicitly concurrency-focused
|
||||
work. If the upstream capability is unavailable, this is the recommended
|
||||
fallback after deliberately updating the release/testing policies; do not
|
||||
block adoption indefinitely or silently run the complete suite twice.
|
||||
## Open Decisions
|
||||
|
||||
### 2. How Much Static Analysis Should Publication Require?
|
||||
|
||||
**Recommendation:** Keep full vet through a configured `go vet ./...` check
|
||||
initially, and ask ReleaseKit to consider full vet as part of its one standard
|
||||
test operation. Current `go test` includes only a subset of analyses, so full
|
||||
vet can catch additional defects. The transitional command costs virtually
|
||||
no local implementation, though it repeats some analysis.
|
||||
|
||||
**Alternative:** Use only ReleaseKit's standard `go test` vet subset and run
|
||||
full vet during ordinary development. This most closely follows the minimal
|
||||
upstream baseline and removes overlapping analysis; it trades away release-time
|
||||
coverage of the omitted analyses. Either choice requires updating the existing
|
||||
explicit static-analysis requirement rather than assuming the checks are
|
||||
equivalent.
|
||||
|
||||
### 3. Should Adoption Add Hosted Gitea Release Notes?
|
||||
### 1. Include Hosted Gitea Release Notes In This Adoption?
|
||||
|
||||
**Recommendation:** Adopt source publication first and leave hosted delivery
|
||||
for a separately selected expansion. Source publication already provides the
|
||||
desired standardization. PromptKit currently has no hosted CI, and adding a
|
||||
delivery workflow and credentials is additional operational scope rather than
|
||||
a prerequisite for using ReleaseKit.
|
||||
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 in adoption, using
|
||||
the upstream maintained workflow and the committed note as the hosted body.
|
||||
This follows ReleaseKit's broader consumer direction and improves release
|
||||
discoverability with little bespoke code. It requires provisioning CI and a
|
||||
Gitea credential, plus keeping delivery status and retries separate from source
|
||||
publication. Successful tag publication still completes the release, even
|
||||
when page delivery is delayed or fails.
|
||||
**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.
|
||||
|
||||
### 4. Is The Credential-Pattern Scan Worth Retaining As A Gate?
|
||||
### 2. Retire Or Retain The Credential-Pattern Gate?
|
||||
|
||||
**Recommendation:** Retire the mandatory release scan and retain the existing
|
||||
credential-aware ordinary change review. The regex offers narrow detection
|
||||
and can reject synthetic fixtures; there is no evidence in this assessment
|
||||
that it provides enough additional protection to warrant preserving it as a
|
||||
shared release requirement. This changes the selected check, not the obligation
|
||||
to keep actual credentials out of committed source.
|
||||
**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:** Keep the small check, or request an optional shared equivalent,
|
||||
if catching a few recognizable accidentally committed credential formats is
|
||||
worth its low execution cost and possible false positives. This provides an
|
||||
independent automated signal beyond review. Its supported formats and intended
|
||||
scope should remain explicit, without treating it as comprehensive detection
|
||||
or making a broader scanner a prerequisite for adoption.
|
||||
**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.
|
||||
|
||||
Reference in New Issue
Block a user