eric/ConfigKit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Plan the single-command release workflow

Browse Source
This commit is contained in:
Eric Rakestraw
2026-09-28 00:52:16 +00:00
parent faf5ff8fa1
commit d6fe498652
2 changed files with 190 additions and 272 deletions
Download Patch File Download Diff File Expand all files Collapse all files

403
docs/roadmap/implementation.md
View File

@@ -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 ## Scope and settled decisions
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.
The adopted shared wording is upstream wording, not a local paraphrase. Remove Start from completed policy alignment at `faf5ff8`. Follow the
template-adoption sections and customize only metadata, necessary references, [development guide](../development.md) and applicable adopted policies. Preserve
project-specific topics, and the substantive exceptions selected below. Preserve library behavior, dependencies, the everyday checker, historical release notes,
unrelated work. Do not reconstruct older adoption baselines or write uncertainty licensing, and support commitments. This plan authorizes no real release or push.
narratives. New source metadata records the deliberate adoption made here.
This is documentation work only. Do not change Go code, tests, dependencies, Use release policy 1.4 and the adoption guide at upstream commit
scripts, existing release commands, gates, platforms, tags, historical release `d84a38ebab26f048cafbe59a2246700c35d29843`, available from `../policy` or the
notes, or accepted ADR decision text. The [release-workflow roadmap](release.md) existing pinned upstream links. Do not add an upstream-version review. Use shared
is a separate task and remains unchanged. Do not add policy synchronization, wording verbatim unless a substantive ConfigKit decision warrants adaptation.
scanners, mandatory legal reviews, per-file license headers, or new guarantees. 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, Use sequential explicit main-then-tag pushes, not atomic-push negotiation. Keep
set `Last Updated` to the actual local adoption date, and add: Bash 3.2 and existing Git/Go prerequisites; no new release framework is needed.
```text ## Stage 1 — Simplify the release checker and select its gates
**Upstream Source:** [Standard Repository Policies](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/FILENAME.md)
```
Replace FILENAME with that document's filename. Use these actual upstream Change `scripts/release-check.sh`, checker tests in `release_check_test.go`, and
template versions: meta 1.0; agents 1.3; architecture 1.3; testing 1.3; the affected descriptions in `docs/policy/release.md`, `docs/release.md`, and
documentation 1.11; OSS 1.8; release 1.4. Local adaptations remain explicit in `docs/development.md` together. The existing guarded publication blocks remain
the document rather than being hidden by the version label. Do not claim that operational until Stage 2; do not describe the new command as available yet.
all documents have already been updated while later stages remain outstanding.
### 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 | Gate | Command and rationale |
governing its work, the affected upstream documents, and the local documents being | --- | --- |
revised. Reuse unchanged policy text already in context. Inspect Git status and | 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. |
the diff before editing. For this cross-policy task, read all adopted policies | 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. |
over the course of the work; this is not a new blanket-reading rule for other tasks. | 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 Remove the disposable-copy module-tidiness audit, release formatting/whitespace
local difference using the selected adaptations below, not incidental baseline scans, and their unused machinery. Formatting/whitespace remain ordinary
wording. A review summary is sufficient; do not create a permanent diff ledger. development checks in `scripts/check.sh`; module tidiness is reviewed when
- Run `GOPROXY=off go test . -run '^TestLocalDocumentationLinks$'` and dependencies change. Offline tests/builds establish that the candidate compiles
`git diff --check`; after staging, run `git diff --cached --check` as well. and works with its declared dependencies. Remove policy wording that makes the
Acquire missing dependencies explicitly if necessary; do not weaken checks. removed checks mandatory release gates. Shell syntax checks belong to development
- Inspect new files, metadata URLs, anchors, and license scope manually. Compare validation, not a separate publication gate. Do not change the everyday checker.
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.
The local link checker can encounter Markdown examples inside fenced blocks. Split the shared checker regression expectations where their contracts differ.
Keep examples meaningful and repair their destinations or link to the actual Retain unusual-filename and whitespace tests for the everyday checker. Controlled
upstream example when necessary. Do not add placeholder files, alter the checker, Go subprocesses should verify the release toolchain/offline settings, one suite,
or copy the upstream example collection to satisfy illustrative links. 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, ## Stage 2 — Implement single-command publication and recovery
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.
### 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 ### Candidate and publication flow
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.
### 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/<version>.md` from
that commit and require the first line `# ConfigKit <version>`. 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/<version>:refs/tags/<version>`, 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 Use straightforward private helpers. These are ordinary release guards, not a
pass, and metadata reflects only adoption actually performed. Standard policy guarantee against hostile local processes or concurrent administrators. Do not
attribution identifies the adapted files/section accurately. No published note, add locks, snapshots, signing requirements, or unrelated Git configuration rules.
release behavior, root license text, or code changed.
## Stage 2 — Align agent, architecture, and testing policies ### Failure outcomes
**Completed 2026-09-28.** Adopted the pinned agent, architecture, and testing After a failed or ambiguous push, perform one bounded authoritative-state check;
policy wording with the selected ConfigKit constraints and expanded the single do not poll or blindly retry:
attribution entry. The local documentation-link and whitespace checks passed;
the pinned-text comparison, metadata review, and staged diff review confirmed
the local adaptations.
### 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 Document exact-ref recovery commands that distinguish absence from query failure.
existing substantive local additions: the paragraph explaining why correctness Only after confirming a local tag was never published or used by another channel
constraints must follow requested behavior rather than implementation convenience; may a maintainer delete that unpublished tag and rerun with the same version.
the qualification that existing explicit contracts remain authoritative and A fresh invocation revalidates; this is failure recovery, not a mandatory double
changing them needs a deliberate decision; and the paragraph rejecting successful-path run. A correctly published tag needs no rerun. Published source
repeated agent-authored artifacts as evidence of approval. Drop other local defects need a new version; transient transport failures do not. Never roll back
paraphrases or slogans where upstream already expresses the same rule. main or automatically delete tags to recover.
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.
### Acceptance ### Regression coverage and acceptance
Shared rules match upstream text; preserved local differences have the specific Use disposable real Git working repositories and bare remotes. Reuse the existing
reasons above. Public API, configuration invariants, callback/ownership boundaries, fixture-only authoritative-URL substitution or Git URL rewriting, with local-file
existing security contracts, and commit authority are neither narrowed nor transports and isolated identity/signing configuration. No production test-only
strengthened. No architectural refactor or test rewrite was performed. 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, Acceptance: Bash syntax checks, focused checker/publication tests, and the offline
retained the existing source-only runbook and historical exceptions, expanded default suite pass. The script is tested only against fixtures. Current docs must
the single attribution entry, and closed the policy roadmap. All seven policy no longer require a manually recorded candidate before single-command publication.
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.
### Work ## Stage 3 — Complete documentation alignment and integrated validation
1. Compare the current release policy with pinned upstream v1.4. Use upstream Reconcile `docs/policy/release.md` with the pinned upstream release policy. Adopt
shared wording for purpose, compatibility principles, immutable publication, shared paragraphs verbatim except for substantive local decisions. Remove the
and successful-push/no-CI completion where semantically equivalent. Keep local temporary deferral, all-remotes freshness rule, and stale prospective v0.3.0 note
operational sections and their headings where required by the current runbook instruction. Preserve known-published-version nonreuse, ConfigKit compatibility,
and inbound links. This is a selected adoption with substantive local workflow source-only deliverables, annotated tags, selected gate rationale, Linux support,
adaptations, not a wholesale replacement of the body. best-effort macOS, no-CI completion, and historical exceptions. No compensating
2. Set Base Policy Version to 1.4 and the exact upstream source/date metadata. controls are required merely to use successful-tag-push completion.
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.
### 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 Review `docs/release.md` as the operational owner: preparation, one publication
contains only the authorized documentation/notice/license files. The current command, completion, partial/unknown-state recovery, and distinctly optional
runbook still agrees with the adopted release policy, and no code, test, script, diagnostics. Retain exact version-specific licensing footer URLs and optional
dependency, gate, support commitment, or publication mechanism changed. Report consumer retrieval; neither adds a network gate. Remove duplicate manual publish
the stage commits and checks, and explicitly identify the release workflow as instructions. Update `docs/development.md` navigation, gate summary, and test map.
remaining future work. 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 Correct the completed policy roadmap's implementation-record reference to
and push strategy remain open only in the separate release-workflow roadmap. `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.

59
docs/roadmap/release.md
View File

@@ -1,6 +1,7 @@
# Single-Command Release Workflow and Gate Review # 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 ## Intent and baseline
@@ -55,19 +56,19 @@ must remain separate; this task introduces none.
## Gate review target ## Gate review target
Keep the full deterministic offline suite as the core check. Evaluate every Keep the full deterministic offline suite as the core check. The selected gates
additional current gate for distinct protection, cost, and overlap; do not retain below provide distinct protection without repeating validation. Their rationale
or remove it solely because it appears in a template. Record the selected rationale belongs in the adopted release policy, with commands in the runbook and tooling
in the adopted release policy, with commands in the runbook and implementation. 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. | | Race detector | One full race-enabled suite protects ownership and concurrent loads; no second ordinary suite. |
| Vet | What additional static defects does it catch beyond the test invocation, and is that protection worth a separate gate? | | Vet | One full vet pass provides additional static analysis; disable the smaller test-time vet pass to avoid overlap. |
| Module hygiene | Is reproducibility protection distinct from ordinary dependency-change review and offline tests? | | 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 | Which checks belong in ordinary development rather than blocking publication? Avoid repeated scans without distinct value. | | Formatting and whitespace | Ordinary development checks, not publication gates; the everyday checker remains unchanged. |
| Linux amd64/arm64 builds | Preserve existing supported targets unless deliberately changed; remove only demonstrably redundant work, not support commitments by implication. | | Linux amd64/arm64 builds | Retain both CGO-disabled builds: they cover supported configurations distinct from native race compilation. |
| Toolchain selection | Preserve minimum-line validation without adding a second-toolchain gate or per-release latest-version research. | | 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 Examples, consumer fixtures, documentation links, and import/public boundary tests
are already in the suite; they must not become separately repeated release checks. 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 local repositories, without real publication or credentials. Match coverage to
the chosen push strategy and protect against unintended refs or stale candidates. 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. Operational documentation changes land with the implementation they describe.
No library behavior, dependency update, release tag, or push is authorized by No library behavior, dependency update, release tag, or push is authorized by
implementing this roadmap alone. implementing this roadmap alone.
## Open Decisions ## Publication strategy
### Final gate set 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
Recommendation: use the current single race suite and Linux support matrix as the intermediate result is possible; recovery distinguishes it from completed or
starting point, retaining additional checks only with specific nonredundant unknown publication. Atomic publication is not part of this target.
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.
## Completion criteria ## 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 gate set, no duplicate suite runs, and automated exact-source safeguards. Local
regression tests demonstrate successful publication and safe failure handling. regression tests demonstrate successful publication and safe failure handling.
The policy, runbook, and scripts agree, and successful tag publication is reported The policy, runbook, and scripts agree, and successful tag publication is reported
without waiting for external completion evidence. Detailed stages belong in the without waiting for external completion evidence.
later implementation plan, not this target-state roadmap.