144 lines
8.1 KiB
Markdown
144 lines
8.1 KiB
Markdown
# Single-Command Release Workflow and Gate Review
|
|
|
|
Status: accepted target; detailed design and implementation planning remain separate.
|
|
|
|
## Intent and baseline
|
|
|
|
Make source releases simple for humans and agents: one publication command
|
|
validates the final committed candidate, checks publication state, and publishes
|
|
only the intended refs. Keep the minimum gates justified by ConfigKit's actual
|
|
risks, with no routine human intervention or waiting for CI.
|
|
|
|
Local baseline: `0adb94f59e44827908eff401d4381a398fe17107` (v0.4.1).
|
|
The upstream reference is release policy v1.4 at
|
|
`d84a38ebab26f048cafbe59a2246700c35d29843`:
|
|
[standard release policy](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/release.md).
|
|
|
|
Today, `scripts/release-check.sh` performs local validation; the runbook separately
|
|
records a candidate commit and executes shell blocks for guards, branch push,
|
|
annotated tagging, and tag push. The checker runs module hygiene, formatting and
|
|
whitespace checks, one race-enabled suite, vet, and Linux amd64/arm64 cross-builds
|
|
using a maintained Go 1.25 patch. Publication completes on successful tag push.
|
|
|
|
These remain the current requirements until deliberately revised. This roadmap
|
|
does not itself waive existing gates.
|
|
|
|
## Target release contract
|
|
|
|
ConfigKit remains a source-only Go module hosted at its authoritative Gitea
|
|
remote. Releases identify a final committed source revision on `main`, one fresh
|
|
immutable annotated version tag, and a matching checked-in release note.
|
|
No binary distribution, hosted release object, or registry publication is added.
|
|
|
|
The publication command owns validation, candidate identity, guards, and explicit
|
|
ref publication. Preparation still supplies the version, committed release note,
|
|
and dependencies/toolchain; the command must not silently edit or commit source,
|
|
choose a version, or upgrade dependencies. Publication remains subject to user
|
|
authorization, not the standing local-commit policy.
|
|
|
|
The command validates the exact candidate once. An optional validation-only mode
|
|
may support diagnosis but is not a prerequisite followed by duplicate validation.
|
|
Do not require both everyday and release checkers. An implementation need not
|
|
introduce a persistent validation cache merely to replace today's manual record.
|
|
|
|
Mechanical guards ensure a clean worktree/index on the primary branch, an unused
|
|
valid version locally and on the authoritative remote, a matching release note,
|
|
and exact agreement between validated source and tagged source. Publish only
|
|
intended refs without discarding remote history. Ignored local files are not
|
|
release content and do not alone prevent publication.
|
|
|
|
A successful intended tag push, with the source commit available on authoritative
|
|
main, completes the release. Never wait for or poll CI, module availability,
|
|
consumer installation, or optional verification. Do not add a successful-push
|
|
remote read-back gate. If future artifact channels are adopted, delivery status
|
|
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.
|
|
|
|
| Current check | Review question |
|
|
| --- | --- |
|
|
| 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. |
|
|
|
|
Examples, consumer fixtures, documentation links, and import/public boundary tests
|
|
are already in the suite; they must not become separately repeated release checks.
|
|
macOS remains best-effort. No human sign-off, new linter, hardware requirement,
|
|
scanner, credentials-dependent test, or remote application probe is introduced.
|
|
|
|
## Documentation and recovery
|
|
|
|
Align `docs/policy/release.md` with upstream shared wording, preserving explicit
|
|
ConfigKit decisions and the selected gate rationale. The successful-tag-push rule
|
|
is a normal supported choice under the new upstream policy, not an exception
|
|
requiring newly invented compensating controls.
|
|
|
|
Make `docs/release.md` a short executable runbook for preparation and the single
|
|
command. New notes use a proportionate summary and applicable compatibility and
|
|
upgrade information rather than mandatory empty sections. Preserve the licensing
|
|
footer and version-specific immutable links. Derive annotated-tag summary content
|
|
from the checked-in note. Keep historical notes unchanged.
|
|
|
|
Validation or guard failure stops publication with actionable diagnostics and no
|
|
force updates. A failed or ambiguous push requires resolving authoritative remote
|
|
state before retrying or reporting success. A transient failure does not itself
|
|
require a new version. Published tags remain immutable; removing an unpublished
|
|
local tag requires confirmation it was never published. Explain partial progress
|
|
such as a successful branch push followed by a failed tag push.
|
|
|
|
## Changes needed and scope
|
|
|
|
The work affects `docs/policy/release.md`, `docs/release.md`, release shell tooling,
|
|
`release_check_test.go`, and relevant contributor guidance. Reuse existing
|
|
validation mechanisms where appropriate; avoid a general release framework.
|
|
Tests should exercise success and meaningful failure/recovery paths in disposable
|
|
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).
|
|
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
|
|
|
|
### 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.
|
|
|
|
## Completion criteria
|
|
|
|
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.
|