Plan ReleaseKit migration stages
This commit is contained in:
193
docs/roadmap/implementation.md
Normal file
193
docs/roadmap/implementation.md
Normal file
@@ -0,0 +1,193 @@
|
||||
# Implement ReleaseKit adoption
|
||||
|
||||
Status: Planned. Implement the stages below in order. The target state and
|
||||
policy choices are in the [ReleaseKit adoption roadmap](releasekit.md); this
|
||||
plan is the execution checklist. Use ReleaseKit v0.2.0 at tagged commit
|
||||
`e030794969fb7787e647a90bbc4eb81bd0610f07` for the initial migration.
|
||||
Do not publish a real ConfigKit version as part of implementation. Keep the
|
||||
current release procedure authoritative until the replacement is working.
|
||||
Follow the task-specific reading guide in [development.md](../development.md)
|
||||
and avoid adding gates, compatibility promises, or restrictions beyond the
|
||||
roadmap and adopted policies. Stages 3–5 are one documentation-and-machinery
|
||||
cutover; their intermediate state is not a release candidate.
|
||||
|
||||
## Stage 1: Select Go and declare the release tool
|
||||
|
||||
1. Identify the newest Go executable available in the development environment
|
||||
when implementing this stage. Make it the `go` on `PATH`, verify it with
|
||||
`GOTOOLCHAIN=local go version`, and advance ConfigKit's `go.mod` `go`
|
||||
directive to its full version. Do not substitute a newer downloaded
|
||||
toolchain during later validation. Record the resulting minimum-Go increase
|
||||
for the next release's compatibility review; before v1.0.0, an intentional
|
||||
increase requires a minor release, not a patch release.
|
||||
2. Using that same Go executable, add
|
||||
`gitea.maximumdirect.net/eric/ReleaseKit/cmd/releasekit@v0.2.0` as a
|
||||
`go.mod` tool dependency (the Go `tool` directive and its module
|
||||
requirement). Update `go.sum`, run `go mod tidy`, and inspect the module
|
||||
diff. Preserve ConfigKit's runtime dependency boundary: production library
|
||||
packages must not import ReleaseKit. Do not introduce a second tool-version
|
||||
pin or an `@version` installation path in the release procedure.
|
||||
3. Prepare the module cache and build the selected CLI package with that Go
|
||||
executable into a temporary path outside the worktree. Confirm that the
|
||||
resolved ReleaseKit module is v0.2.0 and that the built executable runs.
|
||||
Review actual dependency and license treatment under the
|
||||
[OSS policy](../policy/oss.md); a tool used only for development and release
|
||||
work does not by itself require an attribution entry.
|
||||
|
||||
Completion evidence: `go.mod` selects the chosen Go version and the pinned
|
||||
ReleaseKit tool, `go.sum` is consistent, `go mod tidy` leaves no unintended
|
||||
changes, the module-selected executable builds with the selected Go, and the
|
||||
ordinary offline Go suite still passes after dependencies are prepared.
|
||||
|
||||
## Stage 2: Add ConfigKit's ReleaseKit profile
|
||||
|
||||
1. Add `releasekit.json` at the repository root with `product` set to
|
||||
`ConfigKit`, `remote` set to `origin`, and `expected_push_url` set to
|
||||
`https://gitea.maximumdirect.net/eric/ConfigKit.git`. Select
|
||||
`validation.go.race: true`, `validation.go.full_vet: true`, and
|
||||
`validation.go.compile_targets` in this order: `linux/amd64`, `linux/arm64`.
|
||||
Omit `build`, `delivery`, `checks`, and the other optional validation
|
||||
selections. This is a source-only release; macOS is best effort.
|
||||
2. Add one small, offline ConfigKit-owned test of the committed profile's
|
||||
selected identity, endpoint, and checks. Keep it limited to configuration
|
||||
wiring and the agreed gate set; do not replicate ReleaseKit's publication,
|
||||
recovery, or Go-check implementation tests. Stage 6 will exercise the
|
||||
profile with the actual tool against an isolated remote.
|
||||
|
||||
Completion evidence: the profile is valid JSON, the focused test and ordinary
|
||||
Go suite pass, and review shows only the selected gates and no binary or hosted
|
||||
delivery configuration.
|
||||
|
||||
## Stage 3: Align release policy with the adopted workflow
|
||||
|
||||
1. Revise [the release policy](../policy/release.md) so candidate preparation
|
||||
explicitly publishes the committed candidate to authoritative `main`
|
||||
before the one ReleaseKit `publish` invocation validates it and publishes
|
||||
the annotated tag. Keep the checked-in note and tag as the only deliverables,
|
||||
successful intended-tag publication as completion, and CI, macOS, hosted
|
||||
delivery, and consumer retrieval outside release gates.
|
||||
2. Replace references to the local release scripts and fixed Go 1.25 release
|
||||
baseline with the selected local Go executable, the current `go.mod`
|
||||
minimum, the module-selected ReleaseKit CLI, its one race suite with
|
||||
test-time vet disabled, full vet, and Linux amd64/arm64 package compilation.
|
||||
State that preparation advances `go.mod` to the newest Go available in the
|
||||
development environment and reviews any minimum-version increase under
|
||||
existing compatibility rules. Keep dependency acquisition and tool build
|
||||
before offline candidate validation; do not add a separate successful test
|
||||
or CI run as a publication prerequisite.
|
||||
3. Align the guard descriptions with ReleaseKit v0.2.0: use its release-note
|
||||
H1 and exact effective push-URL checks, rather than claiming an automated
|
||||
exact-first-line or configured fetch-URL check. Retain the required
|
||||
`# ConfigKit <version>` first-line format for notes, the source/tag
|
||||
immutability rules, and the existing recovery principles. Do not require
|
||||
per-test skip listings; test failures still block publication.
|
||||
|
||||
Completion evidence: policy and roadmap agree on order, gates, compatibility,
|
||||
and completion; no policy passage still describes the retired script or its
|
||||
stronger automated guards as current behavior.
|
||||
|
||||
## Stage 4: Replace the maintainer release runbook
|
||||
|
||||
1. Revise [the runbook](../release.md) into copyable steps for the adopted
|
||||
process. During preparation, select the newest Go executable available in
|
||||
the development environment, keep it first on `PATH`, verify its version
|
||||
with `GOTOOLCHAIN=local`, and update `go.mod` to that full version if needed.
|
||||
Explain the minimum-Go compatibility impact and version choice, including
|
||||
the pre-v1.0.0 minor-release rule. Prepare dependencies, then build the
|
||||
module-selected `cmd/releasekit` with that executable into temporary storage
|
||||
outside the repository. Use the native executable for publication so its
|
||||
exit status and diagnostic state are preserved. Its child Go commands must
|
||||
find the same selected `go` on `PATH`; the old
|
||||
`CONFIGKIT_BASELINE_TOOLCHAIN` selector cannot choose them.
|
||||
2. Keep ordinary candidate preparation: check access to the authoritative
|
||||
remote, choose an unused stable version, review compatibility and content,
|
||||
write `docs/releases/<version>.md` with the exact ConfigKit first line and
|
||||
license footer, retire completed roadmaps, and commit the entire candidate.
|
||||
Do not turn those reviews into additional approval gates. Push only that
|
||||
committed candidate to authoritative `main` using the literal authoritative
|
||||
URL and `HEAD:refs/heads/main` refspec, with implicit tag following
|
||||
disabled. ReleaseKit requires the remote `main` to equal the candidate
|
||||
before it validates. A failure before this push leaves publication
|
||||
unstarted; a failed validation after it leaves an untagged `main` candidate
|
||||
that must be corrected by a new commit and another validation.
|
||||
3. Document one `releasekit publish vMAJOR.MINOR.PATCH` invocation using the
|
||||
built, module-selected executable. Describe its selected race suite, full
|
||||
vet, Linux package builds, release-note and effective-push-URL guards,
|
||||
exact tag publication, and confirmed-tag completion. Keep `check` optional
|
||||
for diagnosis, not a repeated required pass. Update the partial/unknown
|
||||
push recovery directions to ReleaseKit's reported candidate, endpoint,
|
||||
tag-object ID, and bounded authoritative-state reconciliation. Preserve
|
||||
optional post-publication consumer verification and no-CI-wait behavior.
|
||||
Remove old script commands, Go 1.25 pin examples, and promises of verbose
|
||||
skipped-test output.
|
||||
|
||||
Completion evidence: a maintainer can follow the runbook from a clean checkout
|
||||
through confirmed tag publication without a ConfigKit release wrapper or a
|
||||
second required Go/test run; all commands, version placeholders, and documented
|
||||
failure states match ReleaseKit v0.2.0. Do not execute its real publication
|
||||
command in this stage.
|
||||
|
||||
## Stage 5: Retire duplicated machinery and update developer guidance
|
||||
|
||||
1. Remove `scripts/release.sh`, `scripts/release-check.sh`, and
|
||||
`release_publish_test.go` after Stages 1–4 supply the replacement. Remove
|
||||
`TestCheckScriptsReleaseGates` and its now-unused helpers from
|
||||
`release_check_test.go`. Preserve
|
||||
`TestDevelopmentCheckHandlesFilenamesAndStopsOnFailure` and
|
||||
`scripts/check.sh`; rename the test file if helpful so its name reflects
|
||||
its remaining owner. Retain the small Stage 2 profile-wiring test. Do not
|
||||
transplant the old publication guard/recovery matrix into ConfigKit tests.
|
||||
2. Update [the development guide](../development.md) to point to the new
|
||||
release runbook, remove retired-script references and the fixed release
|
||||
baseline, and adjust its task-to-test map. Keep the everyday development
|
||||
check and release validation distinct. Review other live references to the
|
||||
removed scripts and update only those made stale by this migration;
|
||||
historical release notes remain unchanged.
|
||||
|
||||
Completion evidence: no live release instruction invokes a removed script;
|
||||
the default suite and `./scripts/check.sh` pass with the selected Go and
|
||||
prepared dependencies; the retained tests protect development checks and
|
||||
profile wiring without duplicating ReleaseKit's generic behavior.
|
||||
|
||||
## Stage 6: Exercise the migration without publishing ConfigKit
|
||||
|
||||
1. Build ReleaseKit from the candidate's `go.mod` selection with the same Go
|
||||
executable declared by that candidate. In disposable Git fixtures, use
|
||||
ConfigKit's selected profile with only `expected_push_url` changed to a
|
||||
temporary bare remote, and provide a matching committed fixture release
|
||||
note. Never push a ConfigKit tag or source commit to its real remote.
|
||||
2. Push a committed fixture candidate to temporary `main` and run the built
|
||||
`publish` command with a deliberately failing fixture test. Confirm
|
||||
validation fails and creates no release tag, while `main` remains at that
|
||||
candidate. Correct and commit the fixture, push the new candidate to
|
||||
temporary `main`, and run `publish` again. Confirm one race-enabled standard
|
||||
suite, one full vet pass, and one CGO-disabled package compile for each
|
||||
selected Linux target in that successful invocation; confirm the remote
|
||||
annotated tag identifies the corrected candidate and contains the checked-in
|
||||
note. Record child Go invocations with a fixture-only forwarding executable
|
||||
on `PATH`, or use equivalent direct evidence, rather than inferring the
|
||||
selected command count merely from success.
|
||||
|
||||
Completion evidence: the isolated failure and success paths demonstrate the
|
||||
selected profile, module-selected tool, command order, gates, and tag-only
|
||||
publication. No ConfigKit ref is pushed to its real remote.
|
||||
|
||||
## Stage 7: Check endpoint failure and finish the cutover review
|
||||
|
||||
1. In a fresh disposable fixture/version without an existing tag, check that
|
||||
a wrong effective push URL is rejected before validation or tag
|
||||
publication. Do not reuse the version already published in Stage 6, which
|
||||
would make the existing-tag guard obscure the endpoint result.
|
||||
2. Compare the runbook's recovery directions with ReleaseKit's reported state
|
||||
for a failed or uncertain tag push. Repair any mismatch in the runbook;
|
||||
do not duplicate ReleaseKit's recovery machinery in ConfigKit. This is a
|
||||
bounded migration exercise, not a new per-release gate or a requirement to
|
||||
wait for CI.
|
||||
3. Re-run the affected repository checks after any corrections. Review the
|
||||
final policy, runbook, development guide, and roadmap together for a
|
||||
coherent process; confirm that only intended files changed and that no
|
||||
real ConfigKit release or push occurred.
|
||||
|
||||
Completion evidence: the wrong-endpoint fixture fails for the intended reason,
|
||||
recovery guidance matches ReleaseKit v0.2.0, tests and documentation checks
|
||||
pass, and the repository is ready for a separately authorized release.
|
||||
@@ -3,8 +3,8 @@
|
||||
Status: Proposed. This roadmap uses ReleaseKit v0.2.0 (tagged commit
|
||||
`e030794969fb7787e647a90bbc4eb81bd0610f07`) as the initial adoption
|
||||
baseline. The [ReleaseKit release note](https://gitea.maximumdirect.net/eric/ReleaseKit/src/tag/v0.2.0/docs/releases/v0.2.0.md)
|
||||
summarizes its available capabilities. A later implementation plan will own
|
||||
task order and acceptance checks.
|
||||
summarizes its available capabilities. The staged
|
||||
[implementation plan](implementation.md) owns task order and acceptance checks.
|
||||
|
||||
## Purpose and current baseline
|
||||
|
||||
|
||||
Reference in New Issue
Block a user