From e6ced0d3d1194b58e0b3dc8970089471ba175258 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Wed, 23 Sep 2026 22:34:50 +0000 Subject: [PATCH] Prepare ConfigKit v0.4.0 --- docs/development.md | 5 + docs/releases/v0.4.0.md | 56 +++++++ docs/roadmap/implementation.md | 210 ------------------------- docs/roadmap/overlays.md | 20 --- docs/roadmap/release-simplification.md | 26 --- 5 files changed, 61 insertions(+), 256 deletions(-) create mode 100644 docs/releases/v0.4.0.md delete mode 100644 docs/roadmap/implementation.md delete mode 100644 docs/roadmap/overlays.md delete mode 100644 docs/roadmap/release-simplification.md diff --git a/docs/development.md b/docs/development.md index 61a6346..af21fc7 100644 --- a/docs/development.md +++ b/docs/development.md @@ -58,6 +58,11 @@ and current facade ownership belongs to the [component overview](internal/overvi ## Baseline validation +The completed overlay rename plan and release-workflow simplification record are +preserved in Git history at `73ce6e9` under `docs/roadmap/`. Current overlay +behavior belongs to the [configuration contract](config.md#selected-overlays), +and release operations belong to the [release procedure](release.md). + Install Go 1.25.0 or a supported patched/newer Go toolchain. Acquire declared dependencies explicitly before entering an offline development or validation environment: diff --git a/docs/releases/v0.4.0.md b/docs/releases/v0.4.0.md new file mode 100644 index 0000000..e64f954 --- /dev/null +++ b/docs/releases/v0.4.0.md @@ -0,0 +1,56 @@ +# ConfigKit v0.4.0 + +This release renames selected configuration profiles to overlays, intentionally +breaking the previous naming contract without compatibility aliases or fallback. + +## Summary + +Selected configuration now uses `Options.Overlay` and `overlays/.yml`. +Selection, merge rules, input precedence, and lifecycle behavior are unchanged. +See the [selected-overlay contract](../config.md#selected-overlays). + +## Compatibility + +This is a breaking minor release before v1.0.0. Four surfaces change: + +- Go API: `Options.Profile` becomes `Options.Overlay`, `LayerProfile` becomes + `LayerOverlay`, and all seven `CodeProfile*` constants become `CodeOverlay*`. +- Selected files: `profiles/.yml` becomes `overlays/.yml`; there is + no legacy-directory fallback. +- Provenance: the layer string changes from `profile` to `overlay`. +- Structured diagnostics: the `profile.*` code prefix becomes `overlay.*`. + +The old Go identifiers are removed. Application-owned concepts such as +`ModelProfile` and `model_profile` are unchanged. Ordinary explicit imports from +a directory named `profiles` remain valid base inputs. + +The minimum Go version remains 1.25. Linux remains release-validated and macOS +remains best-effort. The YAML dependency remains pinned to +`go.yaml.in/yaml/v4 v4.0.0-rc.6`; this release does not change parser dependencies. + +## Upgrade + +Update the dependency: + +```sh +go get gitea.maximumdirect.net/eric/ConfigKit@v0.4.0 +``` + +Rename the affected Go identifiers, move selected files into `overlays/`, update +any handling of provenance-layer and diagnostic-code strings, and rebuild. +The maintained example helper is now `LoadNarratioOverlay` rather than +`LoadNarratioProfile`. Application CLI flag names remain application-owned; +ConfigKit does not require renaming domain-specific profile concepts. +See the [migration guide](../consumers/README.md#selected-overlay-migration). + +## Changes + +- Rename the selected feature consistently across the public facade, internal + engine, diagnostics, source labels, examples, and current documentation. +- Add regression coverage for the new directory, absence of legacy fallback, + public values, explanations, and preservation of application profile fields. +- Align contributor policies with the current shared standard. +- Simplify release validation to one local minimum-toolchain check. CI is not a + release gate; successful publication of the intended tag completes the + source-only release. See the [release procedure](../release.md). +- Retire completed overlay and release-workflow planning documents to Git history. diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md deleted file mode 100644 index 10a1381..0000000 --- a/docs/roadmap/implementation.md +++ /dev/null @@ -1,210 +0,0 @@ -# Configuration Overlay Rename Implementation Plan - -Status: complete. - -## Scope and operating instructions - -This plan implements the approved [overlay roadmap](overlays.md). That document -owns naming, preserved behavior, and the decision to make a breaking minor-release -change without compatibility aliases. Baseline: `d8d9dbf`; implemented code is -unchanged from `aead20f`. The intended release is v0.4.0, but this plan does not -authorize a release, push, tag, dependency upgrade, or downstream repository edit. - -The target implementer is a gpt-5.6-terra coding agent. Each stage is one coherent, -reviewable unit. Stage 1 is broader in file count but is a mechanical rename of -one feature; splitting the public/engine/consumer rename would leave a broken -build or require temporary compatibility machinery. Stage 2 owns the additional -regression evidence and final migration audit, not a second implementation. - -Before each stage: - -- Read `AGENTS.md`, [development guidance](../development.md), and all policies: - [agents](../policy/agents.md), [architecture](../policy/architecture.md), - [documentation](../policy/documentation.md), [testing](../policy/testing.md), - and [release](../policy/release.md). -- Inspect Git status and preserve unrelated work. Prefer the repository's graph - tools for code discovery; use text searches for strings and documentation. -- Read the roadmap and the current selected-input contract in `docs/config.md`. - Inventory references before changing them; do not blindly replace every - occurrence of "profile" across the repository. -- Keep dependencies and toolchains available before offline validation. Use the - normal local development checks, not a real release workflow. Never wait for CI. - -At each stage's end, update this plan's status with completion and validation -evidence, review the diff, and commit that stage with a short plain-English -message under the agent policy. Do not commit failed or incomplete work as if -the stage were complete. Do not repeat checks merely to create the commit. - -## Stage 1 — Rename the feature end to end - -### Outcome - -The repository builds and existing tests pass using the new public API, selected -directory, layer values, diagnostics, and current documentation. No legacy API -aliases or filesystem fallbacks remain. Existing selection/merge semantics stay -unchanged. - -### Implementation - -1. Apply every public mapping in the roadmap's **Target terminology and public - surface** table. Change `Options[T].Profile` to `Overlay` in root - `lifecycle.go` and engine `load.go`, including the facade options conversion. - Change `LayerProfile` to `LayerOverlay` with string value `overlay`, and all - seven `CodeProfile*` constants to their `CodeOverlay*` equivalents and - `overlay.*` strings in both `records.go` files. Remove the old declarations; - do not leave aliases, deprecated fields, or dual emitted values. -2. Keep merge mechanics in `internal/engine/overlay.go`. Rename the acquisition - files `internal/engine/profile.go` and `profile_test.go` to - `selected_overlay.go` and `selected_overlay_test.go`. Use `activeOverlay`, - `validOverlayName`, `loadSelectedOverlayDocument`, `readOverlayFile`, and - `overlayDirectiveDiagnostics` for their corresponding helpers. Rename - test helpers and local variables consistently; do not otherwise refactor the - loading pipeline or merge algorithm. -3. Update engine `options.go`, `load_input.go`, `directives.go`, `overlay.go`, and - `explain_render.go`, plus any other callers found by discovery. Load only - `overlays/.yml`; use the same prefix in source labels. Update diagnostic - messages about the selected feature. Preserve shared `options.*`, `import.*`, - source, and parser classifications where the baseline uses them. -4. Migrate existing tests and assertions, including selected-file tests and - engine `overlay_test.go`, `override_test.go`, `provenance_test.go`, - `metadata_test.go`, `explain_test.go`, `render_test.go`, `glob_test.go`, and - `source_fifo_test.go`. Update names, selected-file paths, expected layers, - codes, and rendered terminology. Preserve the semantic expectations; do not - relax unrelated assertions to obtain a green suite. -5. Rename `LoadNarratioProfile` to `LoadNarratioOverlay` in the maintained - consumer example, update its callers and `Options` literals, and move - `examples/consumers/testdata/narratio/profiles/testing.yml` to - `examples/consumers/testdata/narratio/overlays/testing.yml`. Preserve - `ModelProfile`, its `model_profile` YAML key, and their domain meaning. -6. Update Go declaration/package comments, README, `docs/config.md`, - `docs/consumers/README.md`, architecture-policy terminology, development test - paths/commands, and implemented-component documentation where affected. - Rename the contract heading to **Selected overlays** and repair all inbound - links, including links from this plan or the roadmap if needed. Current docs - must match the Stage 1 implementation; do not postpone that work to Stage 2. -7. In `docs/internal/extraction.md`, distinguish literal upstream symbols and - historical claims from descriptions of current ConfigKit helpers. Preserve - upstream names/revisions; update current ConfigKit references. Preserve - accepted ADR decision text and historical release notes. Repair historical - navigation links only where necessary. No new architecture decision is needed - for this terminology-only change. -8. Add a concise migration section to the consumer guide: rename option/constant - identifiers, move selected files, update handling of layer/diagnostic strings, - and rebuild. Link to current canonical behavior rather than duplicating the - full specification. Explain that application-owned profiles remain unchanged - and any application CLI flag rename belongs to that application. Do not - create `docs/releases/v0.4.0.md` in this implementation stage. - -### Validation and acceptance - -- Run `gofmt` on changed Go files, then `./scripts/check.sh`. Its complete suite - covers the migrated engine tests, maintained consumers, examples, documentation - links, and facade/dependency boundaries; do not rerun these subsets just to - duplicate successful coverage. -- Review that empty selection and lowercase `default` still mean no selection; - the name grammar, `.yml` convention, filesystem checks, error ordering, merge - rules, budgets, CLI precedence, and lifecycle are unchanged. -- Review output assertions to ensure `overlay` and `overlay.*` propagate through - both the engine and public wrappers, including history and explanations. -- Review `git diff` for accidental changes to `model_profile`, historical - evidence, merge logic, dependencies, or release machinery. - -Stage 1 is complete only with a compiling, passing repository and matching -current documentation. It is not permission to ship before Stage 2's audit. - -### Completion - -Completed 2026-09-23. Renamed the selected configuration feature across the -facade, engine, maintained consumer, fixtures, contract, and current guidance; -application-owned `ModelProfile` and `model_profile` remain unchanged. `gofmt` and -`./scripts/check.sh` passed on Go 1.26.8/linux. Review confirmed the new -`overlays/.yml` path, `overlay`/`overlay.*` public values, and no retained -legacy Go declarations or filesystem fallback. - -## Stage 2 — Verify the breaking migration and finalize the handoff - -### Outcome - -Focused regression tests demonstrate the intentional break and protect against -legacy fallback or over-broad renaming. The final public surface and consumer -instructions match the roadmap, with no unresolved migration work in this repo. - -### Implementation and review - -1. Extend the renamed selected-file selection test using real temporary files: - - A selected file under `overlays/` loads successfully. - - The same selected name present only under `profiles/` yields - `CodeOverlayMissing` and no usable result; it is not silently loaded. - - When both locations exist with different values, only the `overlays/` - file contributes to configuration and sources. Assert the selected source's - new label and `LayerOverlay`; do not manufacture extra source records. - Retain the existing empty/default, invalid-name, missing-file, and `.yaml` - no-fallback cases. Reuse existing helpers rather than a new fixture framework. -2. Confirm that a normal explicit import from a directory named `profiles` - remains valid and has base-layer semantics. Add one focused case if existing - import coverage does not establish it. This protects the specific decision - not to reserve or ban the old word outside named-overlay selection. -3. Verify the public facade with the maintained consumer test. Extend that test - only as necessary to assert its application-owned `ModelProfile` remains - intact while overlay selection and public source metadata use the new names. - Engine tests own the detailed negative cases; do not replicate them all at - the root boundary. -4. Check coverage for the new public layer/code string values and explanation - output. Prefer the migrated behavioral assertions; if a mapping lacks - coverage, add a small assertion at its existing owner. Do not introduce a - blanket ban on the text "profile" in diagnostics or user data, and do not - snapshot human wording that is not contractual. -5. Inspect `go doc -all .` and source references against the baseline. Confirm - that `Options.Profile`, `LayerProfile`, and `CodeProfile*` declarations are - gone, that all roadmap mappings exist, and that no unrelated exported API - changed. A manual source/API review is sufficient for removal of old Go - identifiers; no negative-compilation harness or whole-API golden file is - required. -6. Audit remaining case-insensitive "profile" references in tracked content. - Classify rather than delete them automatically. Legitimate remaining uses - include application fields, immutable history/upstream evidence, migration - guidance, this plan, and explicit negative/no-fallback test fixtures. Repair - any active ConfigKit feature names, stale file paths, or heading links. -7. Finish migration guidance and any gaps found in current docs alongside fixes. - Record that v0.4.0 release preparation must explain all four breaking - surfaces: Go API, selected-file directory, provenance layer, and diagnostic - codes. Actual version selection, release-note creation, tagging, and pushing - remain a separately authorized release task using the existing procedure. -8. Once validated, mark this plan complete and reduce the feature roadmap to a - completion summary linking to the current configuration contract and consumer - migration guidance. Retain completed records until release preparation; - do not leave competing normative definitions in roadmap documents. - -### Validation and acceptance - -Run `./scripts/check.sh` for changed code and docs. Run -`GOPROXY=off go test -race ./internal/engine` for the final migrated engine, -including the existing concurrent-load independence coverage. Do not introduce -new release gates, external integration tests, CI waits, or mandatory macOS -checks. If a broader equivalent validation already passed for unchanged content, -reuse that evidence rather than repeating it. - -Report the stage commit, validation results, any skipped platform-specific cases, -and the API/filesystem migration summary. The implementation is complete only -when both stages pass and the roadmap's target surface and preserved behavior -are accounted for. There are no unresolved product questions in this plan. - -### Completion - -Completed 2026-09-23. Added regression coverage that accepts only -`overlays/.yml` for selection, rejects a legacy-only selected file with -`CodeOverlayMissing`, and ignores a legacy sibling when the new selected file is -present. Explicit imports from a directory named `profiles` remain base-layer -imports. The maintained consumer confirms `ModelProfile` is unchanged while its -selected source reports `overlays/testing.yml` and `LayerOverlay`; public -layer/code strings and rendered explanation values are covered. - -Validation passed with `./scripts/check.sh` and `GOPROXY=off go test -race -./internal/engine` on Go 1.26.8/linux. No additional platform-specific validation -was required; existing symlink coverage remains conditional on Linux or macOS. -The API audit found no legacy Go declarations, and the remaining `profile` -references are intentionally limited to application-domain fields, upstream or -historical records, migration guidance, and explicit legacy-path regressions. The -feature roadmap is now a completion summary; v0.4.0 release preparation must still -describe the Go API, selected-file directory, provenance layer, and diagnostic-code -breaks. diff --git a/docs/roadmap/overlays.md b/docs/roadmap/overlays.md deleted file mode 100644 index dbbfd5b..0000000 --- a/docs/roadmap/overlays.md +++ /dev/null @@ -1,20 +0,0 @@ -# Configuration Overlay Rename - -Status: implementation complete; release preparation remains separate. - -ConfigKit now calls the selected configuration feature an overlay. The current -behavior is owned by the [selected-overlay contract](../config.md#selected-overlays), -and upgrade instructions are in the [consumer migration guide](../consumers/README.md#selected-overlay-migration). - -The completed migration intentionally changed four breaking surfaces: - -- Go API identifiers, including `Options.Overlay`, `LayerOverlay`, and - `CodeOverlay*`; -- selected-file location to `overlays/.yml` without a `profiles/` fallback; -- provenance layer value to `overlay`; and -- diagnostic-code strings to `overlay.*`. - -Application-owned profile concepts, including `ModelProfile` and `model_profile`, -remain unchanged. A future v0.4.0 release-preparation task must describe all four -breaking surfaces. Versioning, release notes, tagging, publishing, dependency -updates, and downstream changes are not part of this completed implementation. diff --git a/docs/roadmap/release-simplification.md b/docs/roadmap/release-simplification.md deleted file mode 100644 index 44518d8..0000000 --- a/docs/roadmap/release-simplification.md +++ /dev/null @@ -1,26 +0,0 @@ -# Release Workflow Simplification - -Status: implemented; retain this completion record until release preparation. - -## Outcome - -The maintainer-approved simplification is implemented in the -[release policy](../policy/release.md), [procedure](../release.md), and -[checker](../../scripts/release-check.sh). Those documents own current requirements. - -The workflow uses one minimum-toolchain local race-suite run, vet, module hygiene, -formatting/whitespace, and Linux cross-builds. Redundant suite/subset runs and -routine human sign-offs have been removed. CI never gates publication or -completion; a successful push of the intended tag completes the release. -Post-publication verification is optional under the explicit policy exception. - -The [check-script and runbook tests](../../release_check_test.go) cover the -reduced command set, failure handling, and publication guards using disposable -local repositories. Implementation does not authorize an actual release. - -## Scope - -No library API, configuration, or runtime behavior changes were made. Published -tag immutability, release notes, compatibility rules, and exact-candidate -publication safeguards remain in place. There is no remaining implementation -work or unresolved product decision for this roadmap.