eric/ConfigKit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Plan the staged overlay rename

Browse Source
This commit is contained in:
Eric Rakestraw
2026-09-23 18:20:25 +00:00
parent d8d9dbfe7f
commit 66e080ed34
2 changed files with 209 additions and 55 deletions
Download Patch File Download Diff File Expand all files Collapse all files

83
docs/roadmap/overlays.md
View File

@@ -1,6 +1,7 @@
# Rename Configuration Profiles to Overlays
Status: approved target, not yet implemented.
Status: approved target, not yet implemented. Execution steps and stage status
belong to the [implementation plan](implementation.md).
## Purpose and release scope
@@ -91,61 +92,35 @@ Ordinary explicit imports retain their existing rules regardless of a file's
directory name. Removing legacy selection support does not reserve or ban these
names elsewhere.
## Work required from the baseline
## Internal architecture and maintained examples
### Public facade and engine
The public facade retains root-owned named types and inward-only dependencies.
Selected-file acquisition and the existing overlay merge mechanism remain
distinct responsibilities within the engine. Internal naming reflects the new
terminology without a pipeline or merge-algorithm redesign.
Update root `lifecycle.go`, `records.go`, and package/API comments along with
their engine counterparts. Rename selection helpers, variables, and tests that
refer to ConfigKit profiles. Preserve root-owned public types and inward-only
dependencies; no facade redesign is needed.
Maintained examples use the new API and selected-file directory. The Narratio
example still has an application-owned `ModelProfile` / `model_profile`; that
concept is deliberately independent of ConfigKit overlay selection.
The existing `internal/engine/overlay.go` owns merge mechanics. Keep that role
distinct from selected-file acquisition: rename `profile.go` and its tests to
`selected_overlay.go` and `selected_overlay_test.go`, with names such as
`loadSelectedOverlayDocument` for acquisition. Do not combine unrelated code
merely to resolve the filename collision. Update option validation, directive
checks, input loading, and explanation rendering consistently.
## Documentation and migration contract
### Tests and maintained consumer examples
Current public comments, configuration documentation, consumer guidance,
architecture terminology, and implementation descriptions consistently call the
feature an overlay. Accepted ADR decisions and historical release notes retain
their historical wording. The extraction inventory preserves literal upstream
symbols and revision-specific evidence while distinguishing current ConfigKit
implementation names. Historical navigation links may change when their targets
move; historical decisions do not change.
Migrate existing coverage and fixtures rather than duplicating the entire suite.
Update assertions for layer/code values, labels, paths, and rendered output;
retain all existing semantic assertions under the new terminology.
Consumer migration consists of updating Go identifiers, moving selected files to
`overlays/`, and updating any handling of the renamed provenance-layer and
diagnostic-code strings. Applications own any corresponding CLI flag rename;
ConfigKit does not define or modify downstream CLIs.
Add focused regression evidence that selection uses `overlays/`, never falls
back to `profiles/`, and chooses only `overlays/` when both exist. Preserve coverage
for empty/default selection, invalid and missing names, root containment,
version/directive rules, source budgets, CLI precedence, and provenance/history.
Existing public-boundary and consumer tests must continue to pass after their
API migration. A source/API review must confirm that old exported names were
removed, not hidden behind aliases.
Move the maintained Narratio fixture from `profiles/testing.yml` to
`overlays/testing.yml`, update the example helper and callers, and keep its
application-owned `ModelProfile` / `model_profile` unchanged. This distinction is
part of the motivation for the rename, not leftover work.
### Documentation and consumer migration
Update the canonical configuration heading and inbound links, public Go
reference comments, README, architecture policy terminology, development
test map, consumer guide, and implemented-component descriptions as applicable.
The architecture itself remains unchanged.
Do not globally replace every occurrence of "profile". Preserve immutable
historical release notes and accepted ADR decision content. Preserve upstream
symbol names and revision-specific evidence in the extraction inventory while
updating its descriptions of the current ConfigKit implementation. Historical
navigation links may be repaired when headings or files move.
At release preparation, the version-matched minor-release note must explicitly
describe the breaking API, directory, provenance-layer, and diagnostic-code
changes. Consumer instructions must cover updating Go identifiers, moving
selected files to `overlays/`, and updating any downstream output/diagnostic
handling. Applications own any corresponding CLI flag rename; ConfigKit does
not define or modify downstream CLIs. Do not create a release note before an
actual reviewed release candidate exists.
The future minor-release note must explain those four breaking surfaces. Release
preparation and publication remain governed by the [release procedure](../release.md);
this roadmap does not create a release candidate or introduce additional gates.
## Completion criteria
@@ -156,11 +131,9 @@ and no directory fallback. Remaining "profile" references must be intentional
application data, migration explanation, or historical records, not active
ConfigKit feature names.
Validate locally under the [testing policy](../policy/testing.md), including
affected behavioral tests, examples, documentation links, facade boundaries,
formatting, vet, and builds. Publication is a separate task governed by the
[release procedure](../release.md); neither CI waiting nor additional release
gates are introduced by this roadmap.
Tests establish the new selection directory, absence of legacy fallback, and
preservation of existing semantics. Existing coverage remains with its owning
layer instead of being duplicated across the facade and engine.
After implementation, current contracts own the renamed behavior and this
roadmap becomes a completion record for retirement during release preparation.