Align release policy and complete policy adoption
This commit is contained in:
@@ -4,9 +4,9 @@
|
||||
|
||||
Material: `docs/policy/meta.md`, `docs/policy/oss.md`,
|
||||
`docs/policy/documentation.md`, `docs/policy/agents.md`,
|
||||
`docs/policy/architecture.md`, and `docs/policy/testing.md`; root
|
||||
`AGENTS.md`; and the Policy Reading Guide in `docs/development.md`, adapted
|
||||
for this repository.
|
||||
`docs/policy/architecture.md`, `docs/policy/testing.md`, and
|
||||
`docs/policy/release.md`; root `AGENTS.md`; and the Policy Reading Guide in
|
||||
`docs/development.md`, adapted for this repository.
|
||||
|
||||
Copyright (C) 2026 Eric Rakestraw
|
||||
|
||||
|
||||
@@ -53,7 +53,9 @@ license texts and preserve distinct versions and exceptions.
|
||||
|
||||
Use the commit-pinned upstream examples to create actual project notices.
|
||||
Retain their links and keep the example collection upstream; keep applicable
|
||||
license texts locally as specified above.
|
||||
license texts locally as specified above. The
|
||||
[standard license-text collection](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/oss/licenses/README.md)
|
||||
identifies the available reference texts.
|
||||
|
||||
## Project Licensing
|
||||
|
||||
|
||||
@@ -1,22 +1,25 @@
|
||||
# Release Policy
|
||||
|
||||
**Base Policy Version:** 1.0
|
||||
**Base Policy Version:** 1.4
|
||||
|
||||
**Last Updated:** 2026-09-26
|
||||
**Last Updated**: 2026-09-28
|
||||
|
||||
The licensing-footer requirement incorporates upstream release policy v1.2;
|
||||
other release-workflow changes from that version are not adopted here.
|
||||
**Upstream Source:** [Standard Repository Policies](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/release.md)
|
||||
|
||||
ConfigKit retains its separately invoked checker and guarded
|
||||
[release procedure](../release.md). A single publication command and review of
|
||||
the current gates are future work under the
|
||||
[release-workflow roadmap](../roadmap/release.md).
|
||||
|
||||
## Purpose
|
||||
|
||||
This policy defines the minimum requirements for selecting, validating,
|
||||
publishing, verifying, and correcting releases. Its goal is to make every
|
||||
release intentional, reproducible from an exact source revision, documented
|
||||
for consumers, and safe from retrospective replacement.
|
||||
This policy defines a proportionate workflow for validating and publishing an
|
||||
intended source revision under a fresh version. Releases should require little
|
||||
routine intervention, avoid repeated work, and preserve published contents.
|
||||
|
||||
The repository-specific commands that implement these requirements belong in
|
||||
`docs/release.md`. Historical release summaries belong in `docs/releases/`.
|
||||
Neither document may weaken this policy.
|
||||
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
|
||||
|
||||
@@ -25,7 +28,7 @@ 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, module hygiene, testing, or
|
||||
local target-build validation. Post-publication consumer retrieval is optional,
|
||||
as documented under Policy Exceptions.
|
||||
as described under Release Model.
|
||||
|
||||
The release procedure must define the module path, authoritative remote,
|
||||
supported Go versions and operating-system/architecture targets, prerequisite
|
||||
@@ -55,33 +58,30 @@ selection following this policy's existing compatibility rules.
|
||||
|
||||
## Release Model
|
||||
|
||||
A release consists of:
|
||||
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.
|
||||
|
||||
- one exact source commit reachable from the repository's primary branch;
|
||||
- one immutable version tag identifying that commit;
|
||||
- one version-matched, checked-in release note; and
|
||||
- every artifact, image, package, registry entry, or other deliverable the
|
||||
repository declares for that release.
|
||||
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.
|
||||
|
||||
The repository's primary branch is `main` unless an adopted policy documents
|
||||
an exception. A release candidate must be committed and pushed to that branch
|
||||
before its release tag is published.
|
||||
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.
|
||||
|
||||
The source tag is the authoritative release identity. Published deliverables
|
||||
must be traceable to the tagged source and must agree with its version. A
|
||||
repository may publish source only. When it publishes additional deliverables,
|
||||
its release procedure must enumerate them and define how each is built,
|
||||
identified, published, and verified.
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
A successful push of the intended annotated tag completes the source-only release.
|
||||
Never wait for CI or use its status as a readiness or completion gate. Optional
|
||||
post-publication checks must not delay reporting success.
|
||||
|
||||
## Versioning And Compatibility
|
||||
|
||||
Stable releases use Semantic Versioning in the form `vMAJOR.MINOR.PATCH`, with
|
||||
@@ -196,10 +196,10 @@ copyable commands for performing them.
|
||||
|
||||
## Immutability And Correction
|
||||
|
||||
Published version tags and published deliverables are immutable. Do not move,
|
||||
overwrite, recreate, or delete a published tag. Do not replace an artifact,
|
||||
image, package, checksum, signature, provenance statement, or release note
|
||||
under an already published version.
|
||||
Published version tags and published contents are immutable. Do not move,
|
||||
overwrite, recreate, or delete a published tag, or replace a published artifact,
|
||||
checksum, signature, provenance statement, or release note under that version.
|
||||
The checked-in note at the immutable tag is that release's historical record.
|
||||
|
||||
If validation fails before publication, correct the candidate, rerun the
|
||||
complete gates, and repeat the publication guards. An unpublished local tag
|
||||
@@ -245,15 +245,6 @@ compensating controls. Customizing release mechanics must not silently weaken
|
||||
the policy's integrity, validation, documentation, verification, or immutability
|
||||
requirements.
|
||||
|
||||
For ConfigKit's source-only releases, the maintainer accepts successful publication
|
||||
of the intended tag as sufficient completion evidence. This is an explicit
|
||||
exception to the shared standard's mandatory post-publication verification:
|
||||
authoritative tag read-back and fresh consumer retrieval are optional and
|
||||
non-gating. CI status and downstream retrieval availability must not delay release
|
||||
completion. Compensating controls are local validation of the exact candidate,
|
||||
automated pre-publication guards, matching remote main, verification of the local
|
||||
annotated tag target, explicit ref pushes, and immutable published versions.
|
||||
|
||||
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
|
||||
consumers. This intentionally changes the v0.1.0 configuration contract without a
|
||||
@@ -266,6 +257,3 @@ For v0.2.0 only, the maintainer accepted the successful native macOS check at
|
||||
only. The final candidate still requires the complete Linux release checker.
|
||||
This exception waives only repeating the macOS check after those documentation
|
||||
changes; it does not waive other publication or verification gates.
|
||||
|
||||
Candidate selection and guarded publication remain mandatory; post-publication
|
||||
verification is optional in the [release procedure](../release.md).
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Policy Alignment Implementation Plan
|
||||
|
||||
Status: ready for implementation.
|
||||
Status: complete.
|
||||
|
||||
## Scope and selected decisions
|
||||
|
||||
@@ -197,6 +197,15 @@ strengthened. No architectural refactor or test rewrite was performed.
|
||||
|
||||
## Stage 3 — Align release-policy wording without changing the workflow
|
||||
|
||||
**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.
|
||||
|
||||
### Work
|
||||
|
||||
1. Compare the current release policy with pinned upstream v1.4. Use upstream
|
||||
|
||||
@@ -1,108 +1,20 @@
|
||||
# Standard Policy Documentation Alignment
|
||||
|
||||
Status: accepted target; execution is defined in the [implementation plan](implementation.md).
|
||||
Status: implemented on 2026-09-28. The [implementation record](implementation.md)
|
||||
contains the completed stages and validation evidence.
|
||||
|
||||
## Intent and baseline
|
||||
ConfigKit's seven [adopted policies](../policy/meta.md) now identify the pinned
|
||||
Standard Repository Policies revision
|
||||
`d84a38ebab26f048cafbe59a2246700c35d29843` and their local adaptations.
|
||||
The [developer guide](../development.md#policy-reading-guide) routes tasks to
|
||||
applicable policies. [COPYRIGHT](../../COPYRIGHT) and the
|
||||
[attribution notices](../oss/attribution.md) identify the separately licensed
|
||||
adapted policy and orientation material.
|
||||
|
||||
Align ConfigKit's adopted documentation with Standard Repository Policies while
|
||||
preserving substantive local decisions. Prefer upstream wording verbatim wherever
|
||||
differences are editorial; do not maintain a parallel local paraphrase of shared
|
||||
rules. Customization must serve a locally significant requirement.
|
||||
The [release policy](../policy/release.md) retains ConfigKit's existing
|
||||
operational requirements. The [maintainer runbook](../release.md) remains their
|
||||
command owner. The separate [release-workflow roadmap](release.md) owns future
|
||||
publication automation and gate review; this policy alignment did not implement
|
||||
that workflow.
|
||||
|
||||
Local baseline: `0adb94f59e44827908eff401d4381a398fe17107` (v0.4.1).
|
||||
The selected upstream revision is
|
||||
`d84a38ebab26f048cafbe59a2246700c35d29843`. Its
|
||||
[adoption guide](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/adoption.md)
|
||||
owns the standard adoption procedure. This roadmap covers the adopted policy set,
|
||||
not just `docs/policy/documentation.md`.
|
||||
|
||||
ConfigKit currently has six policies, no `meta.md`, and no per-document
|
||||
`Upstream Source` links. Its contributor guide routes tasks to documents but lacks
|
||||
the upstream selective-reading guidance. Licensing documentation covers the
|
||||
project and YAML dependency but not copied policy material. The release policy
|
||||
has intentionally retained its established workflow.
|
||||
|
||||
Introduce accurate provenance going forward. Do not reconstruct old adoption
|
||||
baselines or add historical-uncertainty narratives.
|
||||
|
||||
## Target policy set
|
||||
|
||||
Remove upstream template instructions after adoption. Retain shared substantive
|
||||
wording unchanged except for necessary local adaptation and working references.
|
||||
|
||||
| Document | Target |
|
||||
| --- | --- |
|
||||
| `docs/policy/meta.md` | Adopt upstream v1.0: local authority, upstream origin, discovery links, and policy provenance. |
|
||||
| `docs/policy/agents.md` | Adopt v1.3 wording, retaining local explanations of correctness constraints, protection of established contracts, and the rule that repeated agent-authored assertions are not evidence of approval. No change to standing commit authority. |
|
||||
| `docs/policy/architecture.md` | Use v1.3 as the customized template while preserving the opinionated library model, root-owned facade, dependency direction, existing invariants, and explicit avoidance of an imposed hexagonal framework. No code restructuring or new threat guarantees. |
|
||||
| `docs/policy/testing.md` | Adopt v1.3 shared wording. Retain ConfigKit-specific priorities and test ownership. Tests protect selected contracts; examples must not imply new rejection rules or mandatory inventories of techniques. |
|
||||
| `docs/policy/documentation.md` | Adopt v1.11 wording with a library-specific ownership table, including policy provenance. Omit inapplicable interfaces and empty placeholder documents. |
|
||||
| `docs/policy/oss.md` | Adopt v1.8 wording with necessary ConfigKit applicability and reference adjustments. Preserve the selected project grant and house interpretation of upstream notice links. |
|
||||
| `docs/policy/release.md` | Adopt compatible wording and accurate source metadata, preserving current operational requirements as explicit local adaptations until the separate release-workflow task lands. Do not describe the future publication command as implemented. |
|
||||
|
||||
Each adopted document identifies its actual upstream template version, local
|
||||
update date, and full commit-specific `Upstream Source` URL. A deliberate adoption
|
||||
from the selected revision establishes the new baseline even where substantial
|
||||
project-specific content remains. Metadata must not imply adoption of upstream
|
||||
requirements deliberately replaced by local rules.
|
||||
|
||||
## Orientation and upstream navigation
|
||||
|
||||
Adapt upstream `agents/AGENTS.md` into the root orientation file. Keep the required
|
||||
agent-policy reading rule and route other reading through `docs/development.md`.
|
||||
The developer guide owns task triggers for all seven policies, including policy
|
||||
reviews through `meta.md`. Readers select applicable policies, reuse unchanged
|
||||
material already in context, follow relevant cross-references, and expand reading
|
||||
when scope changes. Reading the entire suite is not the default.
|
||||
|
||||
Use live upstream project and adoption-guide URLs for discovery. Pin adopted-source
|
||||
and licensing-example URLs to full commits. Keep the upstream README, root agent
|
||||
instructions, contributor guide, adoption guide, and example collection upstream;
|
||||
do not copy them into ConfigKit. Root orientation derives from the upstream
|
||||
`agents/AGENTS.md` template, not its root AGENTS.md.
|
||||
|
||||
## Attribution and licensing target
|
||||
|
||||
Use the upstream canonical Standard Repository Policies entry in
|
||||
`docs/oss/attribution.md`, identifying the actual adapted material and linking its
|
||||
source, COPYRIGHT, and LICENSE at the selected commit. Include adapted orientation
|
||||
material where applicable. Preserve notices and modification identification
|
||||
without adding research or compliance narratives.
|
||||
|
||||
Copy the applicable CC-BY-SA-4.0 text verbatim into `docs/oss/licenses/` and identify
|
||||
the separately licensed policy-document scope in root COPYRIGHT. ConfigKit code
|
||||
retains LGPL-3.0-or-later; root LICENSE retains the project license texts. Original
|
||||
upstream example formatting is CC0 and does not itself require an attribution
|
||||
entry or copying the example collection.
|
||||
|
||||
Normalize the existing YAML entry to the current House Format: the prescribed
|
||||
document title, factual component identification, actual notice filenames,
|
||||
punctuation, and Source link. Remove editorial explanations while retaining
|
||||
upstream notices, copyright statements, license expression, and exact source
|
||||
revision. Keep MIT and Apache texts unchanged. Do not restore the author-owned
|
||||
adaptation section that the maintainer expressly removed.
|
||||
|
||||
## Change surface and boundaries
|
||||
|
||||
Affected files are the policy documents, root `AGENTS.md`, `docs/development.md`,
|
||||
COPYRIGHT, `docs/oss/attribution.md`, and the new CC license text. Repair affected
|
||||
local links and any misleading licensing summaries. Shared rules belong in their
|
||||
owning policies, not duplicated in the orientation guide or attribution entries.
|
||||
|
||||
The [release-workflow roadmap](release.md) owns publication automation and gate
|
||||
selection. This work may align wording and references but does not alter release
|
||||
scripts, existing gates, supported platforms, publication completion, or library
|
||||
behavior. Coordinate edits to the release policy rather than maintaining two
|
||||
competing definitions. Published tags and historical release notes remain intact.
|
||||
|
||||
## Completion criteria
|
||||
|
||||
The policy set uses upstream language except for justified local substance,
|
||||
contains accurate forward-looking adoption metadata, and has working orientation
|
||||
and attribution links. Existing local contracts and explicit maintainer decisions
|
||||
remain intact. Documentation-link and whitespace checks, license-text comparisons,
|
||||
and ordinary content review provide proportionate validation. No synchronization
|
||||
service, scanner, legal sign-off, or new release gate is introduced.
|
||||
|
||||
This roadmap defines the desired end state and local policy choices. It
|
||||
authorizes neither publication nor a release.
|
||||
These completed records remain until normal release preparation retires them.
|
||||
|
||||
Reference in New Issue
Block a user