From d6fe498652476999223be6b7ec12855518c79460 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Mon, 28 Sep 2026 00:52:16 +0000 Subject: [PATCH] Plan the single-command release workflow --- docs/roadmap/implementation.md | 403 ++++++++++++++------------------- docs/roadmap/release.md | 59 ++--- 2 files changed, 190 insertions(+), 272 deletions(-) diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index ba17bda..ef495a0 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -1,267 +1,202 @@ -# Policy Alignment Implementation Plan +# Release Workflow Implementation Plan -Status: complete. +Status: ready for implementation; no stages completed by this planning pass. -## Scope and selected decisions +Implement the [release roadmap](release.md) in the numbered order below. Each +stage is a bounded work unit for a gpt-5.6-terra coding agent; finish its tests +and current documentation before committing it. The completed policy-alignment +record formerly at this path is preserved at +`faf5ff8:docs/roadmap/implementation.md`; use `git show` to read it. -Implement the [policy roadmap](policy.md), in the stages below, for a -gpt-5.6-terra coding agent. The roadmap owns intent and target state; this plan -owns execution. Local planning baseline is `6f372e0`. Use upstream commit -`d84a38ebab26f048cafbe59a2246700c35d29843` throughout, not whatever upstream main -contains when implementation starts. Read its -[adoption guide](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/adoption.md) -and selected source files at that revision. The sibling `../policy` checkout is -a convenient source; use `git show` at the pinned commit rather than trusting its -working-tree contents. If unavailable, retrieve that exact revision outside this -repository. Do not update or modify the sibling checkout as part of this task. +## Scope and settled decisions -The adopted shared wording is upstream wording, not a local paraphrase. Remove -template-adoption sections and customize only metadata, necessary references, -project-specific topics, and the substantive exceptions selected below. Preserve -unrelated work. Do not reconstruct older adoption baselines or write uncertainty -narratives. New source metadata records the deliberate adoption made here. +Start from completed policy alignment at `faf5ff8`. Follow the +[development guide](../development.md) and applicable adopted policies. Preserve +library behavior, dependencies, the everyday checker, historical release notes, +licensing, and support commitments. This plan authorizes no real release or push. -This is documentation work only. Do not change Go code, tests, dependencies, -scripts, existing release commands, gates, platforms, tags, historical release -notes, or accepted ADR decision text. The [release-workflow roadmap](release.md) -is a separate task and remains unchanged. Do not add policy synchronization, -scanners, mandatory legal reviews, per-file license headers, or new guarantees. +Use release policy 1.4 and the adoption guide at upstream commit +`d84a38ebab26f048cafbe59a2246700c35d29843`, available from `../policy` or the +existing pinned upstream links. Do not add an upstream-version review. Use shared +wording verbatim unless a substantive ConfigKit decision warrants adaptation. +Preserve exact source metadata; update the local date when revising policy. -### Provenance convention +The interface is `./scripts/release.sh vMAJOR.MINOR.PATCH`, with the existing +`CONFIGKIT_BASELINE_TOOLCHAIN` prerequisite. Resolve the repository root from the +script location. Retain `scripts/release-check.sh` as its validator and an optional +diagnostic command, never a required prior run. No skip-validation option, +persistent cache, routine confirmation, or automatic commit is needed. Stop using +`.git/configkit-release-candidate`; ignore any old record without deleting it. -For each policy adopted in a stage, remove its old partial-adoption preamble, -set `Last Updated` to the actual local adoption date, and add: +Use sequential explicit main-then-tag pushes, not atomic-push negotiation. Keep +Bash 3.2 and existing Git/Go prerequisites; no new release framework is needed. -```text -**Upstream Source:** [Standard Repository Policies](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/FILENAME.md) -``` +## Stage 1 — Simplify the release checker and select its gates -Replace FILENAME with that document's filename. Use these actual upstream -template versions: meta 1.0; agents 1.3; architecture 1.3; testing 1.3; -documentation 1.11; OSS 1.8; release 1.4. Local adaptations remain explicit in -the document rather than being hidden by the version label. Do not claim that -all documents have already been updated while later stages remain outstanding. +Change `scripts/release-check.sh`, checker tests in `release_check_test.go`, and +the affected descriptions in `docs/policy/release.md`, `docs/release.md`, and +`docs/development.md` together. The existing guarded publication blocks remain +operational until Stage 2; do not describe the new command as available yet. -### Validation and commit discipline +Use this exact gate set with the selected maintained Go 1.25 baseline: -Before each stage, read AGENTS.md, the developer reading guide, the local policies -governing its work, the affected upstream documents, and the local documents being -revised. Reuse unchanged policy text already in context. Inspect Git status and -the diff before editing. For this cross-policy task, read all adopted policies -over the course of the work; this is not a new blanket-reading rule for other tasks. +| Gate | Command and rationale | +| --- | --- | +| Full offline race suite | One `go test -mod=readonly -vet=off -race -v ./...`; protects library behavior, ownership, and concurrent use. Includes examples, consumer fixtures, documentation links, and boundary tests. | +| Static analysis | One `go vet -mod=readonly ./...`; full vet provides checks beyond the subset normally run by tests. Disabling test-time vet avoids duplicating that subset. | +| Supported target compilation | `go build -mod=readonly ./...` for Linux amd64 and arm64 with `CGO_ENABLED=0`; these configurations are not covered by native race compilation. | -After each coherent stage: +Keep `GOPROXY=off`, baseline availability/cache diagnostics, fail-fast behavior, +and verbose skip reporting. Dependency/toolchain acquisition is explicit +preparation; there is no automatic upgrade or latest-version survey. Readonly +module commands prevent incidental manifest edits, not impose a new tidy policy. -- Review the diff against the pinned upstream text. Account for every substantive - local difference using the selected adaptations below, not incidental baseline - wording. A review summary is sufficient; do not create a permanent diff ledger. -- Run `GOPROXY=off go test . -run '^TestLocalDocumentationLinks$'` and - `git diff --check`; after staging, run `git diff --cached --check` as well. - Acquire missing dependencies explicitly if necessary; do not weaken checks. -- Inspect new files, metadata URLs, anchors, and license scope manually. Compare - copied standard license bytes with the pinned upstream source. Reuse results - for unchanged content rather than repeating full suites. -- Update this plan with the stage's completion and validation evidence, review - staged changes, and commit only that stage with a short plain-English message. - No push, publication, or release is authorized. +Remove the disposable-copy module-tidiness audit, release formatting/whitespace +scans, and their unused machinery. Formatting/whitespace remain ordinary +development checks in `scripts/check.sh`; module tidiness is reviewed when +dependencies change. Offline tests/builds establish that the candidate compiles +and works with its declared dependencies. Remove policy wording that makes the +removed checks mandatory release gates. Shell syntax checks belong to development +validation, not a separate publication gate. Do not change the everyday checker. -The local link checker can encounter Markdown examples inside fenced blocks. -Keep examples meaningful and repair their destinations or link to the actual -upstream example when necessary. Do not add placeholder files, alter the checker, -or copy the upstream example collection to satisfy illustrative links. +Split the shared checker regression expectations where their contracts differ. +Retain unusual-filename and whitespace tests for the everyday checker. Controlled +Go subprocesses should verify the release toolchain/offline settings, one suite, +one vet pass, the two target builds, and stopping after failure. Do not recursively +execute the real full suite in a checker-orchestration test. -## Stage 1 — Establish provenance, orientation, and licensing ownership +Acceptance: focused `TestCheckScripts` tests and Bash syntax checks pass. Run the +real revised checker with prepared baseline dependencies on Linux. Do not also +run the everyday suite just to repeat its checks. macOS and newer-toolchain +validation remain optional. -**Completed 2026-09-28.** Adopted pinned meta, OSS, and documentation policies, -selective orientation, policy attribution, document-license scope, and the -verbatim CC BY-SA 4.0 text. The local documentation-link check, whitespace -checks, pinned license-byte comparison, metadata/link review, and staged diff -review passed. +## Stage 2 — Implement single-command publication and recovery -### Work +Add executable `scripts/release.sh`, calling the existing validator once rather +than duplicating it. Replace `TestReleaseRunbookGuards` with tests of the actual +script: prose headings cease to be an executable interface. Update the release +policy and runbook in this stage to describe implemented behavior and recovery. -1. Create `docs/policy/meta.md` from the pinned template, retaining its live - project and main-branch adoption-guide discovery URLs. Apply the provenance - convention and preserve its distinction between local authority and optional - future upstream adoption. Keep the adoption guide itself upstream. -2. Adopt upstream `docs/policy/oss.md` v1.8, including its copied-document scope, - factual attribution format, and house interpretation of upstream notice links. - Retain a concise ConfigKit applicability section identifying the selected - LGPL-3.0-or-later grant and linking to COPYRIGHT, LICENSE, and the release - procedure for the source-only Gitea channel. Do not require a hosted release - object. Retarget upstream application/library COPYRIGHT examples, attribution - examples, and retained reference-collection links to the selected full commit. - Do not copy those examples. Preserve substantive upstream wording elsewhere. - For the illustrative README link block, a link to the actual local README - may replace the block if needed to avoid invalid example-relative links. - Keep its two-statement requirement intact. Repair the release-correction link - to the local `immutability-and-correction` anchor. -3. Adopt upstream `docs/policy/documentation.md` v1.11. Retain shared sections - verbatim and adapt the ownership table for ConfigKit: retain the existing - root Go declaration owner, configuration contract, consumer examples, internal - documents, ADRs, deferred scope, and release-note history; add meta ownership. - Omit CLI, HTTP API, operations, and integration-contract documents because - ConfigKit has no such owned interfaces. Preserve local distinctions between - `deferred.md` and execution plans, executable Go examples and complete example - files, and retirement of completed roadmaps during release preparation. - Do not create empty owners. Update licensing rows to the upstream scope. -4. Adapt root AGENTS.md from upstream `agents/AGENTS.md`, not upstream root - AGENTS.md. Preserve any independent local tooling instructions encountered. - Adopt its selective-reading orientation and mandatory agent-policy reference. - Merge the adoption guide's seven-row Policy Reading Guide and its reading - rules into `docs/development.md` verbatim except for necessary Go-library - terminology. Keep the existing task-to-contract and task-to-test navigation, - validation commands, and historical references. Remove duplicate policy - trigger prose rather than maintain conflicting reading rules. -5. Create a Standard Repository Policies attribution entry using the pinned - `examples/licensing/policy-attribution.md`. Preserve its copyright, SPDX, - license/notice labels, and three commit-specific URLs after substitution. - Copy `docs/oss/licenses/CC-BY-SA-4.0.txt` verbatim from upstream. At this stage, - identify the newly adopted meta, OSS, and documentation policies, root agent - orientation, and the Policy Reading Guide section of development.md as adapted - material; expand the single entry as later stages adopt the other policies. - Do not claim that unrelated parts of the developer guide were copied. -6. Add the guide's document-license scope statement to COPYRIGHT, extended to - include the adapted orientation material identified by the attribution entry. - Keep code LGPL-3.0-or-later, root LICENSE unchanged, and third-party terms intact. - Do not convert the whole repository to CC-BY-SA or copy CC0 merely because - upstream example formatting is used. The CC0 formatting alone needs no entry. -7. Normalize `docs/oss/attribution.md`: title `Open Source Attribution Notices`, - then the policy entry and existing go-yaml entry, without introductory or - concluding editorial prose. Use the current House Format for go-yaml: factual - module/version identification, existing copyright statements and - `Apache-2.0 AND MIT`, links labeled Apache 2.0, MIT, NOTICE, LICENSE, a period - after the link list, and `[Source](COMMIT_URL).` Preserve its exact upstream - hash and both local license texts. Remove the explanatory final paragraph. - Do not restore author-owned adaptation notices. -8. Leave README's existing license/attribution navigation in place if accurate. - If clarification is needed, state that the LGPL grant applies to ConfigKit - code and let COPYRIGHT own the separately licensed-document scope; do not - duplicate the attribution list or policy text in README. +### Candidate and publication flow -### Acceptance +1. Accept exactly one stable version argument using the existing no-leading-zero + Semantic Version format. Require `main` and a clean index/worktree including + nonignored untracked files. Ignored local files alone do not block release. + Verify the existing authoritative `origin` endpoint and ensure pushes actually + target it, accounting for separately configured push URLs and multiple push + destinations. Do not publish to an unnoticed additional destination or print + credentials in diagnostics. +2. Capture the full candidate commit ID. Read `docs/releases/.md` from + that commit and require the first line `# ConfigKit `. Meaningful + summary and applicable compatibility/upgrade content are ordinary preparation, + not automated prose judgments or four mandatory headings. Retain the existing + footer and local note-review requirements without a new network check. +3. Require the version unused locally and on the authoritative remote. Query the + exact remote tag, distinguishing absence from query failure. Read remote main + and check that publication can advance it without discarding history; main + already at the candidate is acceptable. No all-remotes or all-tags survey. +4. Run `scripts/release-check.sh` once. Failure stops before any push/tag creation. + Recheck branch, cleanliness, candidate identity, and unused version state after + validation. Changed candidates require a fresh invocation after correction and + commit; do not automatically commit or repair the checkout. +5. Push the captured commit explicitly to `refs/heads/main`, without force or + incidental follow-tags publication. Override broad configured push defaults + through explicit destinations/refspecs. A successful push establishes branch + publication without a separate read-back gate. Recheck local candidate and + clean state before tagging; ordinary concurrent local edits must not leak + into publication. +6. Create an annotated tag at the captured commit, using the captured checked-in + note as its message (`git tag -a -F`). Verify its peeled target and capture its + tag-object ID. Push only `refs/tags/:refs/tags/`, without + force or implicit publication of unrelated tags. +7. On successful tag push, report the version/candidate and return success + immediately. No CI polling, remote read-back, module retrieval, hosted release + creation, or routine human sign-off gates completion. -New documents and references are present, license-text comparison and link checks -pass, and metadata reflects only adoption actually performed. Standard policy -attribution identifies the adapted files/section accurately. No published note, -release behavior, root license text, or code changed. +Use straightforward private helpers. These are ordinary release guards, not a +guarantee against hostile local processes or concurrent administrators. Do not +add locks, snapshots, signing requirements, or unrelated Git configuration rules. -## Stage 2 — Align agent, architecture, and testing policies +### Failure outcomes -**Completed 2026-09-28.** Adopted the pinned agent, architecture, and testing -policy wording with the selected ConfigKit constraints and expanded the single -attribution entry. The local documentation-link and whitespace checks passed; -the pinned-text comparison, metadata review, and staged diff review confirmed -the local adaptations. +After a failed or ambiguous push, perform one bounded authoritative-state check; +do not poll or blindly retry: -### Work +| State observed | Behavior | +| --- | --- | +| Main push failed, but remote main equals candidate | Continue through remaining guards and tagging. | +| Main push failed, remote differs or cannot be queried | Stop before tagging; distinguish rejection from unknown outcome and explain recovery. | +| Tag push failed, but remote tag-object ID equals the created annotated tag | Report confirmed publication success; main publication was already established. | +| Tag push failed, remote tag confirmed absent | Report branch-only progress and the unpublished local tag; retain it. | +| Remote tag conflicts | Stop; never replace published contents. | +| Remote tag cannot be queried | Report unknown status; retain local state, do not claim success or safe version reuse. | -1. Adopt upstream agents v1.3 and its commit policy verbatim. Retain exactly the - existing substantive local additions: the paragraph explaining why correctness - constraints must follow requested behavior rather than implementation convenience; - the qualification that existing explicit contracts remain authoritative and - changing them needs a deliberate decision; and the paragraph rejecting - repeated agent-authored artifacts as evidence of approval. Drop other local - paraphrases or slogans where upstream already expresses the same rule. -2. Adopt architecture v1.3 as a customized template, not as a new architecture. - Use upstream Purpose And Ownership and Adopted Constraints And Implemented - Structure wording. Populate application-specific content with existing local - purpose/success criteria, responsibility boundaries, public facade/dependency - direction, configuration integrity, ownership/confidentiality, and scope rules. - Preserve all their substantive requirements. The upstream hexagonal-framework - recommendation is replaced by ConfigKit's existing proportionate separation - and explicit no-imposed-framework decision. Retain explanatory ADR and contract - links. Do not add a threat model, threat exclusions, hardening promises, or a - required security document: the existing confidentiality/input boundaries remain - the selected scope. Avoid duplicate normative descriptions across sections. -3. Adopt testing v1.3 shared text. Retain the local ConfigKit-specific priorities - section and the short preference for real parsing/composition/decoding seams. - Replace upstream generic test-layer ownership examples with ConfigKit's YAML, - composition/overlay, decoding, metadata/rendering, filesystem, and lifecycle - ownership list; preserve the distinction from required package layout. - Retain local guidance preferring codes, paths, and locations at the public - library boundary in place of the CLI-specific example. Use upstream conditional - testing-technique wording, revised concurrency example, and explicit authority - requirement for tested contracts. This changes guidance, not existing tests or - established ConfigKit semantics. Do not turn example techniques into new gates. -4. Apply the source/version/date convention to all three documents. Expand the - existing policy attribution entry's Material sentence to include them; do not - create per-policy attribution entries or a second provenance registry. +Document exact-ref recovery commands that distinguish absence from query failure. +Only after confirming a local tag was never published or used by another channel +may a maintainer delete that unpublished tag and rerun with the same version. +A fresh invocation revalidates; this is failure recovery, not a mandatory double +successful-path run. A correctly published tag needs no rerun. Published source +defects need a new version; transient transport failures do not. Never roll back +main or automatically delete tags to recover. -### Acceptance +### Regression coverage and acceptance -Shared rules match upstream text; preserved local differences have the specific -reasons above. Public API, configuration invariants, callback/ownership boundaries, -existing security contracts, and commit authority are neither narrowed nor -strengthened. No architectural refactor or test rewrite was performed. +Use disposable real Git working repositories and bare remotes. Reuse the existing +fixture-only authoritative-URL substitution or Git URL rewriting, with local-file +transports and isolated identity/signing configuration. No production test-only +bypass flags. Stub the expensive validator with a loggable result; use real +rejection hooks and narrow Git-process wrappers for lost responses/unavailable +queries. Tests must never contact the actual remote or recurse into the suite. -## Stage 3 — Align release-policy wording without changing the workflow +Cover success with main initially behind the candidate and already equal; +single validation; note-derived annotated tag/commit identity; ignored files; +and unrelated local tags remaining unpublished. Cover malformed version, wrong +branch/destination, dirty/changed candidate, missing/mismatched note, local/remote +tag collision, failed validation, non-fast-forward main, and the meaningful +failure outcomes above. A note without empty boilerplate headings must pass. +Assert resulting refs and exit status, not helper structure or exact diagnostics. +Verify completion has no CI/consumer-tool dependency. -**Completed 2026-09-28.** Adopted compatible upstream v1.4 release wording, -retained the existing source-only runbook and historical exceptions, expanded -the single attribution entry, and closed the policy roadmap. All seven policy -versions, dates, pinned source links, live discovery links, attribution scope, -license bytes, local links, and whitespace were reviewed. The staged diff and -documentation-link check passed; only authorized documentation and the CC -license text changed across this plan. The separate release-workflow roadmap -remains future work. +Acceptance: Bash syntax checks, focused checker/publication tests, and the offline +default suite pass. The script is tested only against fixtures. Current docs must +no longer require a manually recorded candidate before single-command publication. -### Work +## Stage 3 — Complete documentation alignment and integrated validation -1. Compare the current release policy with pinned upstream v1.4. Use upstream - shared wording for purpose, compatibility principles, immutable publication, - and successful-push/no-CI completion where semantically equivalent. Keep local - operational sections and their headings where required by the current runbook - and inbound links. This is a selected adoption with substantive local workflow - adaptations, not a wholesale replacement of the body. -2. Set Base Policy Version to 1.4 and the exact upstream source/date metadata. - Replace the old partial-v1.2 preamble with a concise ConfigKit adaptation note: - the existing separately invoked checker and guarded runbook remain in force; - the single-command workflow and gate review are future work. Link to the - current runbook for operations, not to a future command. Record the following - preserved local decisions in the owning policy sections, without duplication: - - source-only Go module, main branch, annotated immutable tags, no prereleases; - - minimum-line Linux validation, existing race/vet/module/format/whitespace - checks and Linux amd64/arm64 builds; macOS best-effort; - - current version-availability scope, note title and four required headings, - licensing footer, and candidate commit recording/revalidation; - - authorization and guards, sequential main-before-tag publication, remote-main - match, and explicit intended refs; - - no CI waiting, no required post-publication retrieval/read-back, and unchanged - historical v0.1.1/v0.2.0 exceptions. - These are preserved requirements, not a fresh endorsement of their permanent - necessity. Their later review belongs to the release-workflow task. -3. Recast the old post-publication-verification exception as a normal local - source-only completion choice supported by upstream v1.4. Preserve its actual - safeguards; do not invent compensating controls. Keep current correction and - recovery semantics; defer changes to push recovery, optional atomic publication, - note structure, and tag-summary generation to the release-workflow task. - Do not copy the upstream single-publication-command requirement into current - binding policy. Do not modify release scripts, tests, or runbook command blocks. -4. Add release.md to the single policy attribution Material scope. At completion, - it may identify all seven files under `docs/policy/`, root AGENTS.md, and only - the adapted Policy Reading Guide in development.md. Keep all source and notice - links accurate at the pinned revision; the text is identified as adapted. -5. Audit all seven policies against the roadmap and this plan. Check each template - version, full source URL, date, live discovery link, pinned example reference, - and absence of template scaffolding. Remove redundant local paraphrases but - retain the explicit local substance. Repair documentation links without editing - historical ADR decisions or releases. Confirm existing licensing navigation - remains correct and that only the new CC license text was added to the asset set. -6. Mark this plan complete with evidence. Change the policy roadmap's status to - implemented and replace future normative detail with a short completion summary - pointing to current owners. Retain these completed records until normal release - preparation retires them. Leave the separate release roadmap and its open - decisions unchanged; do not create a release note or tag. +Reconcile `docs/policy/release.md` with the pinned upstream release policy. Adopt +shared paragraphs verbatim except for substantive local decisions. Remove the +temporary deferral, all-remotes freshness rule, and stale prospective v0.3.0 note +instruction. Preserve known-published-version nonreuse, ConfigKit compatibility, +source-only deliverables, annotated tags, selected gate rationale, Linux support, +best-effort macOS, no-CI completion, and historical exceptions. No compensating +controls are required merely to use successful-tag-push completion. -### Acceptance +Keep base version 1.4 and its existing pinned source; update the local date. +Existing attribution and license scope already cover these edits. Do not change +other policies, copyright/license grants, or historical release notes unnecessarily. -Run the documentation validation described above and confirm the final change set -contains only the authorized documentation/notice/license files. The current -runbook still agrees with the adopted release policy, and no code, test, script, -dependency, gate, support commitment, or publication mechanism changed. Report -the stage commits and checks, and explicitly identify the release workflow as -remaining future work. +Review `docs/release.md` as the operational owner: preparation, one publication +command, completion, partial/unknown-state recovery, and distinctly optional +diagnostics. Retain exact version-specific licensing footer URLs and optional +consumer retrieval; neither adds a network gate. Remove duplicate manual publish +instructions. Update `docs/development.md` navigation, gate summary, and test map. +Search active documentation/scripts for stale candidate-file, section-template, +module-tidiness gate, CI-wait, and manual publication instructions. Fix affected +links without rewriting historical records. -There are no open decisions required for this policy-alignment plan. Gate selection -and push strategy remain open only in the separate release-workflow roadmap. +Correct the completed policy roadmap's implementation-record reference to +`faf5ff8:docs/roadmap/implementation.md`, since this path now owns the new plan. +Mark release-roadmap implementation status accurately after acceptance. Preserve +unfinished/deferred work; retirement belongs to actual release preparation. + +Run Bash syntax checks, focused orchestration tests, documentation-link tests, +and `git diff --check`. Run the revised real release checker once on the final +implementation with prepared baseline dependencies. Reuse that successful suite +result instead of separately repeating examples, boundaries, vet, builds, or the +everyday suite. Report missing prerequisites rather than claiming success. Never +invoke publication against origin as an acceptance test. + +Acceptance: scripts, policy, and runbook agree; tests protect selected behavior +without extra contracts; current docs describe only implemented behavior. Commit +each completed unit with a plain-English message and report validation/workspace +state without publishing. No product decisions remain open in this plan. diff --git a/docs/roadmap/release.md b/docs/roadmap/release.md index 968e7d6..5cca5a2 100644 --- a/docs/roadmap/release.md +++ b/docs/roadmap/release.md @@ -1,6 +1,7 @@ # Single-Command Release Workflow and Gate Review -Status: accepted target; detailed design and implementation planning remain separate. +Status: accepted target; execution order and acceptance checks are defined in the +[implementation plan](implementation.md). ## Intent and baseline @@ -55,19 +56,19 @@ must remain separate; this task introduces none. ## Gate review target -Keep the full deterministic offline suite as the core check. Evaluate every -additional current gate for distinct protection, cost, and overlap; do not retain -or remove it solely because it appears in a template. Record the selected rationale -in the adopted release policy, with commands in the runbook and implementation. +Keep the full deterministic offline suite as the core check. The selected gates +below provide distinct protection without repeating validation. Their rationale +belongs in the adopted release policy, with commands in the runbook and tooling +once implemented. -| Current check | Review question | +| Check | Selected end state and rationale | | --- | --- | -| Race detector | Does its coverage of ownership and concurrent loads justify retaining it as the single full-suite mode? Avoid a second ordinary suite. | -| Vet | What additional static defects does it catch beyond the test invocation, and is that protection worth a separate gate? | -| Module hygiene | Is reproducibility protection distinct from ordinary dependency-change review and offline tests? | -| Formatting and whitespace | Which checks belong in ordinary development rather than blocking publication? Avoid repeated scans without distinct value. | -| Linux amd64/arm64 builds | Preserve existing supported targets unless deliberately changed; remove only demonstrably redundant work, not support commitments by implication. | -| Toolchain selection | Preserve minimum-line validation without adding a second-toolchain gate or per-release latest-version research. | +| Race detector | One full race-enabled suite protects ownership and concurrent loads; no second ordinary suite. | +| Vet | One full vet pass provides additional static analysis; disable the smaller test-time vet pass to avoid overlap. | +| Module hygiene | Tidiness belongs to dependency-change review, not a recurring release audit. Offline tests/builds use readonly module mode to avoid incidental manifest edits. | +| Formatting and whitespace | Ordinary development checks, not publication gates; the everyday checker remains unchanged. | +| Linux amd64/arm64 builds | Retain both CGO-disabled builds: they cover supported configurations distinct from native race compilation. | +| Toolchain selection | One maintained Go 1.25 patch, with no second-toolchain gate or per-release latest-version research. | Examples, consumer fixtures, documentation links, and import/public boundary tests are already in the suite; they must not become separately repeated release checks. @@ -103,35 +104,18 @@ Tests should exercise success and meaningful failure/recovery paths in disposabl local repositories, without real publication or credentials. Match coverage to the chosen push strategy and protect against unintended refs or stale candidates. -Coordinate provenance and licensing with the [policy roadmap](policy.md). +Preserve provenance and licensing established by the completed +[policy roadmap](policy.md). Operational documentation changes land with the implementation they describe. No library behavior, dependency update, release tag, or push is authorized by implementing this roadmap alone. -## Open Decisions +## Publication strategy -### Final gate set - -Recommendation: use the current single race suite and Linux support matrix as the -starting point, retaining additional checks only with specific nonredundant -justification. Assess the remaining checks during implementation planning before -changing the binding policy. This protects selected behavior without treating -the existing checker as an untouchable inventory. - -Alternative: retain the entire existing checker and automate only publication. -This minimizes behavioral change and is a viable initial scope, but it does not -complete the requested gate review unless each retained check is justified. - -### Publication strategy - -Recommendation: retain explicit main-then-tag pushes inside the command. This -matches the proven local workflow and avoids a new dependency on atomic-push -support; recovery must describe a partially published sequence. - -Alternative: atomically push main and the tag after validating remote ancestry. -This avoids a branch-only intermediate result but requires confirming server -support and adapting failure tests. Select one strategy in the implementation -plan rather than silently switching between them. +Use explicit main-then-tag pushes inside the command. This matches the proven +local workflow and avoids a new dependency on atomic-push support. A branch-only +intermediate result is possible; recovery distinguishes it from completed or +unknown publication. Atomic publication is not part of this target. ## Completion criteria @@ -139,5 +123,4 @@ One documented command publishes a prepared candidate with the reviewed minimum gate set, no duplicate suite runs, and automated exact-source safeguards. Local regression tests demonstrate successful publication and safe failure handling. The policy, runbook, and scripts agree, and successful tag publication is reported -without waiting for external completion evidence. Detailed stages belong in the -later implementation plan, not this target-state roadmap. +without waiting for external completion evidence.