Prepare ConfigKit v0.4.0
This commit is contained in:
@@ -58,6 +58,11 @@ and current facade ownership belongs to the [component overview](internal/overvi
|
|||||||
|
|
||||||
## Baseline validation
|
## 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
|
Install Go 1.25.0 or a supported patched/newer Go toolchain. Acquire declared
|
||||||
dependencies explicitly before entering an offline development or validation
|
dependencies explicitly before entering an offline development or validation
|
||||||
environment:
|
environment:
|
||||||
|
|||||||
56
docs/releases/v0.4.0.md
Normal file
56
docs/releases/v0.4.0.md
Normal file
@@ -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/<name>.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/<name>.yml` becomes `overlays/<name>.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.
|
||||||
@@ -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/<name>.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/<name>.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/<name>.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.
|
|
||||||
@@ -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/<name>.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.
|
|
||||||
@@ -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.
|
|
||||||
Reference in New Issue
Block a user