From 897203dd8f6da7aadc246f805b1a45a81457c372 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Mon, 28 Sep 2026 00:32:01 +0000 Subject: [PATCH] Align release policy and complete policy adoption --- README.md | 2 +- docs/oss/attribution.md | 6 +- docs/policy/oss.md | 4 +- docs/policy/release.md | 80 ++++++++++------------ docs/roadmap/implementation.md | 11 ++- docs/roadmap/policy.md | 118 +++++---------------------------- 6 files changed, 66 insertions(+), 155 deletions(-) diff --git a/README.md b/README.md index 2c35792..4193f58 100644 --- a/README.md +++ b/README.md @@ -41,6 +41,6 @@ The [deferred scope](docs/roadmap/deferred.md) records deliberate exclusions. Se [release procedure](docs/release.md) for maintainer-only candidate and publication steps. -ConfigKit is licensed under the [LGPL v3.0 or later](COPYRIGHT). +ConfigKit code is licensed under the [LGPL v3.0 or later](COPYRIGHT). [Open Source attribution notices](docs/oss/attribution.md) are available. diff --git a/docs/oss/attribution.md b/docs/oss/attribution.md index f1ef47a..e91a767 100644 --- a/docs/oss/attribution.md +++ b/docs/oss/attribution.md @@ -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 diff --git a/docs/policy/oss.md b/docs/policy/oss.md index 516e155..731473e 100644 --- a/docs/policy/oss.md +++ b/docs/policy/oss.md @@ -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 diff --git a/docs/policy/release.md b/docs/policy/release.md index ff51b44..f7dd8c7 100644 --- a/docs/policy/release.md +++ b/docs/policy/release.md @@ -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). diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index bde3237..ba17bda 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.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 diff --git a/docs/roadmap/policy.md b/docs/roadmap/policy.md index 3346669..4610ccb 100644 --- a/docs/roadmap/policy.md +++ b/docs/roadmap/policy.md @@ -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.