From 6f372e0dfe43a610e900c58b84170877e9b22bf9 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Mon, 28 Sep 2026 00:12:25 +0000 Subject: [PATCH] Document policy alignment and release workflow roadmaps --- docs/roadmap/policy.md | 108 ++++++++++++++++++++++++++++++ docs/roadmap/release.md | 143 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 251 insertions(+) create mode 100644 docs/roadmap/policy.md create mode 100644 docs/roadmap/release.md diff --git a/docs/roadmap/policy.md b/docs/roadmap/policy.md new file mode 100644 index 0000000..99e3e45 --- /dev/null +++ b/docs/roadmap/policy.md @@ -0,0 +1,108 @@ +# Standard Policy Documentation Alignment + +Status: accepted target; implementation planning remains separate. + +## Intent and baseline + +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. + +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. + +Detailed stages and executable implementation instructions belong in a later +implementation plan. This roadmap authorizes neither publication nor a release. diff --git a/docs/roadmap/release.md b/docs/roadmap/release.md new file mode 100644 index 0000000..968e7d6 --- /dev/null +++ b/docs/roadmap/release.md @@ -0,0 +1,143 @@ +# 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.