Add overlay migration regression coverage
This commit is contained in:
@@ -1,6 +1,6 @@
|
||||
# Configuration Overlay Rename Implementation Plan
|
||||
|
||||
Status: Stage 1 complete. Execute Stage 2.
|
||||
Status: complete.
|
||||
|
||||
## Scope and operating instructions
|
||||
|
||||
@@ -188,3 +188,23 @@ 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,139 +1,20 @@
|
||||
# Rename Configuration Profiles to Overlays
|
||||
# Configuration Overlay Rename
|
||||
|
||||
Status: approved target, not yet implemented. Execution steps and stage status
|
||||
belong to the [implementation plan](implementation.md).
|
||||
Status: implementation complete; release preparation remains separate.
|
||||
|
||||
## Purpose and release scope
|
||||
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).
|
||||
|
||||
ConfigKit's name "profile" collides with application-owned model, pipeline, and
|
||||
execution profiles. The feature already applies a named configuration overlay;
|
||||
use that name directly instead of requiring consumers to distinguish another
|
||||
kind of profile.
|
||||
The completed migration intentionally changed four breaking surfaces:
|
||||
|
||||
The maintainer has approved a breaking rename for the next minor release,
|
||||
intended as v0.4.0. There will be no backward-compatibility aliases, deprecated
|
||||
fields, dual diagnostic names, or legacy-directory fallback. This roadmap does
|
||||
not authorize publication or changes to downstream repositories.
|
||||
- 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.*`.
|
||||
|
||||
The baseline is ConfigKit at `aead20f`, following v0.3.1 and the release-workflow
|
||||
simplification. Current behavior is owned by the
|
||||
[selected-overlay contract](../config.md#selected-overlays). This roadmap owns
|
||||
the unimplemented rename; it is not a new current API reference.
|
||||
|
||||
## Target terminology and public surface
|
||||
|
||||
Use **configuration overlay** in introductory prose and **selected overlay** or
|
||||
**overlay** where context is clear. An overlay is the named configuration input;
|
||||
overlaying is also the merge operation. CLI overrides may use that operation
|
||||
without becoming named configuration overlays or changing their CLI provenance.
|
||||
|
||||
| Current surface | Target surface |
|
||||
| --- | --- |
|
||||
| `Options[T].Profile string` | `Options[T].Overlay string` |
|
||||
| `<configuration-root>/profiles/<name>.yml` | `<configuration-root>/overlays/<name>.yml` |
|
||||
| Source label `profiles/<name>.yml` | Source label `overlays/<name>.yml` |
|
||||
| `LayerProfile`, value `"profile"` | `LayerOverlay`, value `"overlay"` |
|
||||
| `CodeProfileInvalid`, `profile.invalid` | `CodeOverlayInvalid`, `overlay.invalid` |
|
||||
| `CodeProfileMissing`, `profile.missing` | `CodeOverlayMissing`, `overlay.missing` |
|
||||
| `CodeProfileOutsideRoot`, `profile.outside_root` | `CodeOverlayOutsideRoot`, `overlay.outside_root` |
|
||||
| `CodeProfileRepeated`, `profile.repeated` | `CodeOverlayRepeated`, `overlay.repeated` |
|
||||
| `CodeProfileDirective`, `profile.directive` | `CodeOverlayDirective`, `overlay.directive` |
|
||||
| `CodeProfileVersion`, `profile.version` | `CodeOverlayVersion`, `overlay.version` |
|
||||
| `CodeProfileLimitExceeded`, `profile.limit_exceeded` | `CodeOverlayLimitExceeded`, `overlay.limit_exceeded` |
|
||||
| Maintained example `LoadNarratioProfile` | `LoadNarratioOverlay` |
|
||||
|
||||
Apply these changes to public declarations, engine counterparts, facade
|
||||
forwarding/conversion, diagnostics, source records, origin/history records, and
|
||||
rendered explanations. Messages describing this ConfigKit feature use "overlay".
|
||||
Serialization and output that carry the layer or diagnostic-code strings use
|
||||
the new values. No legacy values are emitted for compatibility.
|
||||
|
||||
Not every error during loading currently has a `profile.*` code: shared options,
|
||||
source, import, and parser classifications remain unchanged. This is not an
|
||||
opportunity to redesign error categories or add new diagnostic guarantees.
|
||||
|
||||
## Behavior preserved
|
||||
|
||||
This is a naming migration, not a new layering model. Preserve the existing
|
||||
contract except for the explicitly renamed surfaces:
|
||||
|
||||
- Select at most one overlay by name, not a path or list. Preserve the current
|
||||
ASCII name grammar, case sensitivity, and lack of extension fallback.
|
||||
- Empty selection and exact lowercase `default` continue to mean no selection.
|
||||
`overlays/default.yml` is not implicitly loaded. The sentinel is existing
|
||||
behavior, not a compatibility alias for the old feature name.
|
||||
- Load the selected mapping after strict base composition and schema-version
|
||||
checks, before CLI overrides and defaults/typed decoding. Preserve existing
|
||||
precedence, replacement rules, explicit null/empty behavior, and error ordering.
|
||||
- Preserve filesystem-context requirements, canonical containment and duplicate
|
||||
source checks, aggregate limits, directive/version-path rules, and `NoSource`
|
||||
option validation. Do not strengthen or relax them as part of this rename.
|
||||
- Preserve source-ID ordering, detached metadata, history, provenance queries,
|
||||
callback lifetime, secret handling, and load independence. Only the named
|
||||
layer, selected-file labels/paths, and corresponding diagnostic terminology
|
||||
change where specified above.
|
||||
- Keep CLI overrides and strict composition distinct. Do not add overlay stacks,
|
||||
inheritance, discovery, arbitrary file selection, or new merge options.
|
||||
|
||||
## No backward compatibility
|
||||
|
||||
Old Go identifiers are removed rather than retained as aliases. Applications
|
||||
using them must update before they compile against the new minor version.
|
||||
|
||||
Selection searches only `overlays/<name>.yml`. A file present solely in
|
||||
`profiles/` does not satisfy selection and produces the corresponding new
|
||||
overlay diagnostic. No automatic rename, migration, or search of both locations
|
||||
is performed. If both directories exist, only the selected path under
|
||||
`overlays/` participates in this feature.
|
||||
|
||||
Do not introduce a prohibition against a directory named `profiles`, literal
|
||||
strings containing "profile", or application fields such as `model_profile`.
|
||||
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.
|
||||
|
||||
## Internal architecture and maintained examples
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
## Documentation and migration contract
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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
|
||||
|
||||
The rename is complete when all maintained consumers compile against the new
|
||||
API, selection and reporting consistently use the new terminology, the legacy
|
||||
feature surface is absent, and regression coverage confirms unchanged semantics
|
||||
and no directory fallback. Remaining "profile" references must be intentional
|
||||
application data, migration explanation, or historical records, not active
|
||||
ConfigKit feature names.
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
Reference in New Issue
Block a user