167 lines
9.0 KiB
Markdown
167 lines
9.0 KiB
Markdown
# Rename Configuration Profiles to Overlays
|
|
|
|
Status: approved target, not yet implemented.
|
|
|
|
## Purpose and release scope
|
|
|
|
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 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.
|
|
|
|
The baseline is ConfigKit at `aead20f`, following v0.3.1 and the release-workflow
|
|
simplification. Current behavior is owned by the
|
|
[selected-profile contract](../config.md#selected-profiles). 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.
|
|
|
|
## Work required from the baseline
|
|
|
|
### Public facade and engine
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
### Tests and maintained consumer examples
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
## 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.
|
|
|
|
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.
|
|
|
|
After implementation, current contracts own the renamed behavior and this
|
|
roadmap becomes a completion record for retirement during release preparation.
|