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

Align release policy and operational documentation

Browse Source
This commit is contained in:
Eric Rakestraw
2026-09-28 01:13:09 +00:00
parent 299ebc21a9
commit 3d0093e1fd
7 changed files with 242 additions and 177 deletions
Download Patch File Download Diff File Expand all files Collapse all files

289
docs/policy/release.md
View File

@@ -6,9 +6,6 @@
**Upstream Source:** [Standard Repository Policies](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/release.md)
ConfigKit's [release procedure](../release.md) uses one publication command
with the selected local checker and explicit main-then-tag pushes.
## Purpose
This policy defines a proportionate workflow for validating and publishing an
@@ -19,28 +16,21 @@ The repository-specific commands belong in `docs/release.md`. Historical release
summaries belong in `docs/releases/`. The procedure must agree with the adopted
policy and link to it rather than introduce additional release requirements.
## ConfigKit applicability
## ConfigKit Applicability
ConfigKit adopts a source-only Go module release model. The source tag and
version-matched release note are the declared deliverables. Standalone binaries,
container images, and separate binary/package-registry publication are not
required. This does not waive source compilation, dependency maintenance, testing, or
local target-build validation. Post-publication consumer retrieval is optional,
as described under Release Model.
ConfigKit publishes a source-only Go module. Its declared deliverables are the
immutable annotated source tag and version-matched checked-in release note.
Standalone binaries, container images, hosted release objects, and separate
registry publication are not required. Additional channels require a deliberate
update to the policy and procedure.
The release procedure must define the module path, authoritative remote,
supported Go versions and operating-system/architecture targets, prerequisite
dependency acquisition, and the exact verification commands once established.
The default tests themselves remain deterministic and offline. Additional
publication channels require documented deliverables and verification before use.
The Go API, documented YAML/resolution semantics, and structured diagnostic
contracts all participate in compatibility review. A signature-preserving change
The Go API, documented YAML and resolution semantics, and structured diagnostic
contracts participate in compatibility review. A signature-preserving change
can still break consumers. Human diagnostic wording is stable only where a
contract expressly promises it. Minimum Go version and platform support changes
also require an explicit compatibility assessment.
contract expressly promises it. Minimum Go version and platform support
changes also require an explicit compatibility assessment.
### Platform support
### Platform Support
Linux is the release-validated platform. macOS has best-effort support: keeping
it working remains desirable, but neither native macOS validation nor Darwin
@@ -49,50 +39,59 @@ does not by itself block a release. Voluntary checks and fixes are welcome; ther
is no guarantee that each release has been validated on macOS.
The [release procedure](../release.md#release-identity-and-support) owns target
architectures and required Linux checks. This support change applies to upcoming
releases; historical release notes and their validation records remain unchanged.
The v0.3.0 release note must explain the change in Compatibility, with version
selection following this policy's existing compatibility rules.
architectures and required Linux checks. Historical release notes and their
validation records remain unchanged.
## Release Model
## Release Model And Completion
A source release identifies one exact committed source revision through an
immutable version tag and a version-matched, checked-in release note. ConfigKit's
primary release branch is `main`; its tags are annotated. The
[release procedure](../release.md) names the authoritative publication remote.
immutable version tag and a version-matched, checked-in release note. The
primary release branch is `main` unless the adopted policy specifies otherwise.
The procedure must name the authoritative publication remote.
A successful push of the intended tag, with its source commit available on the
authoritative primary branch, completes the release. ConfigKit publishes the
committed candidate to `main` before pushing only the intended tag.
authoritative primary branch, completes the release. The source commit may be
pushed before the tag or published together with it through an atomic push.
The procedure must choose and document the supported approach.
ConfigKit uses sequential explicit pushes: first the captured candidate to
authoritative `main`, then the annotated tag. Its
[release procedure](../release.md) names `origin` and checks that its fetch and
push destinations resolve to the authoritative URL.
Release commands must finish at successful publication. They must not wait for
or poll CI, require successful CI status, inspect downloadable artifacts, or
check consumer installation or Go module availability as completion gates.
Optional remote tag read-back and fresh consumer retrieval do not delay release
completion.
A failed or ambiguous push requires resolving the authoritative remote state
before declaring success or retrying; successful pushes do not require a
separate remote read-back gate.
ConfigKit publishes source only. If additional deliverables are deliberately
adopted, they must be traceable to the tagged source, identify the same version,
and have documented publication responsibilities and verification.
Remote tag read-back and fresh consumer retrieval are optional and non-gating
after successful publication. A failed push receives one bounded check of the
authoritative ref; do not poll or blindly retry.
Release automation may validate or publish a release only when its exact
responsibility is documented. Automation must not silently change the source
candidate, move a published tag, replace a published deliverable, or repair a
release in place.
Repositories may publish source only. Additional binaries, images, packages,
checksums, or other declared deliverables may be published asynchronously from
the tagged source. The procedure must identify those deliverables and the
responsibility of their automation. Published deliverables must be traceable
to that source and identify the same version.
ConfigKit currently declares no additional deliverables. Its source-tag push
is the completion point.
## Versioning And Compatibility
Stable releases use Semantic Versioning in the form `vMAJOR.MINOR.PATCH`, with
no leading zeroes. The selected version must be unused locally and on the
authoritative remote. A version known to have been published elsewhere must
not be reused.
no leading zeroes. Prereleases require an explicit adopted policy defining
their format and use.
Unless an adopted policy explicitly supports and defines prereleases,
prerelease versions are not permitted.
ConfigKit does not support prereleases.
The selected version must be unused locally and on the authoritative remote.
Do not require queries to every configured remote or publication service.
A version known to have already been published must not be reused, even if the
normal guards do not inspect that channel. Adding a distribution channel
requires a deliberate update to the policy and procedure where needed.
For releases at or after `v1.0.0`:
@@ -105,89 +104,123 @@ configuration, data, integration, or compatibility contract when the release
note explains the impact and required consumer action. A patch release must
not intentionally break those contracts within its minor line.
A repository with additional compatibility promises must define them in its
adopted policy or canonical contract documentation. A release note may explain
a compatibility change, but it must not redefine the current compatibility
contract.
Additional compatibility promises and deliberate exceptions belong in the
adopted policy or canonical contract documentation. Release notes explain
changes; they do not redefine current compatibility contracts.
## Release Documentation
## Release Documentation And Preparation
Every release made under this policy must include
`docs/releases/<version>.md` in the tagged source tree. The filename must use
the complete version tag, and the document must begin with a title containing
the product name and that exact version.
Every new release must include `docs/releases/<version>.md` in the tagged
source tree. Use the complete version tag as the filename and begin with a
title containing the product name and that exact version.
ConfigKit requires the first line `# ConfigKit <version>`.
Include a short summary and any relevant compatibility impact or upgrade
instructions. Choose sections suited to the release and keep the note
proportionate to the change. The annotated tag's message is the checked-in note.
proportionate to the change.
Release notes are immutable historical summaries. They should link to current
canonical documentation for exact behavior. Every affected canonical document
must be updated in the same candidate; a release note must not substitute for
current documentation or defer required documentation changes.
Keep exact current contracts in their canonical documents and update affected
documentation with the behavior change. Link to those documents from the note
where useful. If annotated tags are used, derive their summary from the
checked-in note.
Each new release note must end with the release navigation defined by the
[OSS policy](oss.md#discoverability). Preserve those links on a hosted download
page if one is used. The release procedure owns URL construction and channel
treatment. This is ordinary preparation, not a new network check or approval
gate; historical release notes are unchanged.
ConfigKit uses the complete checked-in note as the annotated tag message.
## Candidate Preparation And Validation
Include the release footer defined by the [OSS policy](oss.md#discoverability)
in each new release document. The release procedure defines the concrete URLs
and publication mechanics. Prepare these links with the release note; they do
not add a network check or approval gate. If a hosted download page is used in
a future channel, preserve the footer there.
The publication command validates the final committed candidate once with
ConfigKit's local release checker, using one maintained patch of the minimum
supported Go line on Linux. The checker runs one full offline race suite, one
full vet pass, and CGO-disabled Linux amd64/arm64 builds. The race suite
protects library behavior, ownership,
and concurrent use; it includes examples, documentation links, consumer fixtures,
and package boundaries without separate runs. Full vet checks more than the
subset normally run by tests, so test-time vet is disabled. The two cross-builds
cover supported configurations that native race compilation does not. A second
toolchain is optional and non-gating.
Handle version selection, release-note content, and retirement of completed
roadmaps during preparation. Preserve planned and deferred work and repair
affected links when retiring roadmaps. Reuse ordinary change review for
unintended files, credentials, and private data. Scope release-content review
to the tagged source.
All Go checks use readonly module mode and an offline dependency cache.
Formatting and whitespace remain ordinary development checks. Review module
tidiness when dependencies change, rather than auditing it on every release.
## Candidate Validation
Commit the release note and associated changes before release validation. The
publication command captures the exact candidate and rechecks it after the
validator. A changed candidate requires a fresh invocation and validation.
Do not publish uncommitted or unvalidated content. Local check failures still
block publication. Skipped test cases are reported, not separate human sign-off
requirements.
Provide one publication command that validates the final committed candidate,
checks publication state, and publishes the intended refs. A validation-only
mode or command may be provided for diagnosis, but must not be a required step
before publication repeats the same checks.
Compatibility review, release-note accuracy, removal of completed roadmaps, and
review for unintended files, credentials, private data, and unrelated changes
are ordinary preparation. The executing agent may perform them without routine
human approval or separate manual evidence records. Ask the maintainer only for
genuine unresolved decisions or missing authority. A clean existing checkout is
sufficient; a dedicated clone is optional. Dependency and toolchain update
research belongs to maintenance or relevant changes, not every release.
ConfigKit uses `./scripts/release.sh vMAJOR.MINOR.PATCH`. The separate
`scripts/release-check.sh` remains an optional diagnostic command; the
publication command invokes it once and does not use a persistent candidate
record.
Run the complete deterministic, offline default test suite once for the final
candidate, following the [testing policy](testing.md). For repositories that
publish builds, verify the required build targets. Select those targets for
the application's actual support commitments; native testing on each platform
and access to particular hardware are not default release prerequisites.
ConfigKit's one maintained Go 1.25 baseline runs the full suite with the race
detector and test-time vet disabled. This protects library behavior, ownership,
and concurrent use; the suite already includes examples, consumer fixtures,
documentation links, and package boundaries. One full vet pass adds static
checks beyond the test-time subset. CGO-disabled Linux amd64 and arm64 builds
cover supported configurations distinct from native race compilation. macOS
and newer-toolchain checks are optional.
Additional gates must address a concrete risk that the existing checks do not
adequately cover. Do not automatically require linting, race testing, module
hygiene audits, documentation audits, credential scans, example validation, or
expanded platform matrices solely because they are possible. Retain such
checks when their distinct protection justifies their cost. A one-time migration
check must not silently become a permanent release requirement.
The selected Go commands use readonly module mode with `GOPROXY=off`; acquire
the baseline toolchain and dependencies before validation. Formatting and
whitespace remain ordinary development checks in `scripts/check.sh`.
Review module tidiness when dependencies change, not as a release gate.
Release tests must not require real credentials, mutable application services,
paid APIs, provider probes, or inference calls. The procedure may describe dependency
preparation separately from offline validation.
Avoid duplicate validation across release phases. Successful checks for the
same final candidate need not be repeated solely to satisfy another phase;
any reuse must clearly apply to that exact candidate. Persistent validation
caches are not required. If the candidate changes, validate the new candidate.
Cheap publication-state checks may be repeated immediately before pushing
because local or remote state may have changed during validation.
Automate mechanical guards. Human review gates are strongly disfavored: add one
only through an explicit project-specific policy decision explaining the
concrete risk and why ordinary change review or automation is insufficient.
Do not add routine confirmations for checks the command can perform itself.
Compatibility review, release-note accuracy, completed-roadmap retirement, and
review for unintended files or credentials remain ordinary preparation. The
executing agent may perform them without routine human approval or separate
manual evidence records. Publication itself requires authorization.
## Publication Guards
Publication requires authorization before invoking the command. The command
must verify all of the following:
Automate the checks needed to publish the intended source under a fresh version:
- the stable version has the required format and is unused locally and on the
- the version has the adopted format and is unused locally and on the
authoritative remote;
- the current branch is `main`, and the worktree and index are clean;
- the committed source and matching release note identify the exact validated
candidate;
- the authoritative remote main can advance to that candidate without
discarding history;
- the local automated gates succeeded for that commit; and
- the annotated tag identifies that candidate and only the intended refs are
- the worktree and index are clean on the primary release branch;
- the source being published is the exact candidate that passed validation,
including its matching release note;
- the remote primary branch can be advanced to that candidate without
discarding remote history, and is published before the tag; and
- the tag identifies the validated candidate and only the intended refs are
published.
Push the exact candidate to authoritative main, then create and verify the
annotated tag before pushing only its ref. Do not use `git push --tags` or
implicit follow-tags publication. A failed or ambiguous push receives one
authoritative-state check before success, rejection, or unknown status is
reported.
ConfigKit also checks that `origin` has exactly the authoritative fetch and
push destination, including configured push URLs. The command checks the
candidate and unused version again after validation, and checks local state
before creating the tag. Ignored local files do not block publication.
The repository-specific procedure must make these guards executable or give
copyable commands for performing them.
Fetch the authoritative branch and tag state as needed for these checks.
Do not force branch or tag updates to bypass a failed guard. Publish explicit
refs rather than all local tags. Do not require CI success, publication-service
availability checks, or a separate manual confirmation for each guard.
## Immutability And Correction
@@ -201,33 +234,33 @@ rerun the publication command. If a push fails or its outcome is ambiguous,
inspect the authoritative remote before retrying. Remove an unpublished local
tag only after confirming it was never published or used by a release channel.
An unavailable remote leaves publication status unknown; do not overwrite a tag
to resolve uncertainty. A transient transport failure alone does not require
a new version.
to resolve uncertainty.
If publication or post-publication verification reveals a defect, leave the
published release intact. Correct the defect on the primary branch, choose a
new patch version or other semantically appropriate new version, write a new
matching release note, and perform the complete release procedure again.
Transient network, authentication, CI, or consumer-availability failures do not
by themselves require a new version.
A distribution channel's supported yank, deprecation, or advisory mechanism
may warn consumers away from a defective release, but it must not replace that
release's contents or reuse its version.
A defect requiring changes to published source or contents requires a corrected
commit, a new semantically appropriate version, a matching release note, and
the release procedure again. Leave the original release intact. A channel's
yank, deprecation, or advisory mechanism may warn consumers away from a defective
release without replacing its contents or reusing its version.
## Repository Release Procedure
Maintain `docs/release.md` as the executable maintainer runbook. It identifies
prerequisites, version and note preparation, the single publication command,
declared deliverables and build targets, successful-tag-push completion, and
partial or unknown-state recovery. Keep optional diagnostics and consumer
verification clearly optional. The procedure must agree with this policy.
Maintain `docs/release.md` as a short, executable maintainer runbook. It must
identify prerequisites, the primary branch and authoritative remote, version
and note preparation, one publication command with local checks and guards,
source-only deliverables, the successful-tag-push completion point, and
partial or unknown-state recovery.
Use copyable commands where practical. Keep optional diagnostics and consumer
verification clearly optional. The procedure must not turn preparation work,
ordinary change review, or post-publication investigation into additional
release gates.
## Policy Exceptions
Any exception to this policy must be explicitly documented in this section,
including the repository constraint requiring it, its rationale, scope, and
compensating controls. Customizing release mechanics must not silently weaken
the policy's integrity, validation, documentation, verification, or immutability
requirements.
The following historical exceptions do not change the current release workflow.
For v0.1.1 only, the maintainer approved renaming the reserved `_configkit` key to
`configkit` as an error-correcting point release because there are no current