Update guidance for the cleaned public API
This commit is contained in:
@@ -99,15 +99,20 @@ records why discovery is explicitly selected.
|
||||
`Options.ImportDefaults` and `LayeredOptions.ImportDefaults` apply one
|
||||
load-wide policy to enabled main, underlay, and transitive imports. Each field
|
||||
is resolved independently: a declaration's explicit value wins, then the
|
||||
application default, then the library default. `Required`, `Follow`, `Hidden`,
|
||||
and `Recursive` use nil pointers for unspecified values. `Pattern` applies to
|
||||
application default, then the library default. `Required`, `FollowSymlinks`,
|
||||
`IncludeHidden`, and `Recursive` use nil pointers for unspecified values.
|
||||
`Pattern` applies to
|
||||
directory searches: nil leaves filenames unrestricted, while a non-nil empty
|
||||
slice selects no files. A declaration's own `pattern` replaces the application
|
||||
default. The defaults do not enable imports or change selected-overlay behavior.
|
||||
The Go fields `FollowSymlinks` and `IncludeHidden` correspond to the unchanged
|
||||
YAML keys `follow` and `hidden`.
|
||||
|
||||
`Result.Sources`, `LoadError.Sources`, and `Resolution.Source` expose each
|
||||
declaring source's `ImportSelections`. These records identify the source-local
|
||||
declaration path, its authored location and selector, and the `none` outcome;
|
||||
declaring source's `EmptyImportSelections`. `Result.Source(id)` and
|
||||
`LoadError.Source(id)` retrieve one retained record directly when its load-local
|
||||
ID is known. These records identify the source-local declaration path, its
|
||||
authored location and selector;
|
||||
they do not include candidate names or a guessed reason for absence. Returned
|
||||
records are detached snapshots. The [configuration contract](../config.md#explicit-imports)
|
||||
owns selector applicability and exact absence semantics.
|
||||
@@ -117,7 +122,7 @@ owns selector applicability and exact absence semantics.
|
||||
[`LoadVersionedService`](../../examples/consumers/source_version.go) demonstrates
|
||||
if-present and required modes with one `Definition.Version` rule across a mounted
|
||||
main input and an underlay. The example reads only sanitized
|
||||
`SourceInfo.VersionCheck` fields; its executable test is in
|
||||
`SourceInfo.VersionEvidence` fields; its executable test is in
|
||||
[`layered_test.go`](../../examples/consumers/layered_test.go). The
|
||||
[configuration contract](../config.md#shared-source-version-checks) defines
|
||||
participation, source-local lookup and diagnostics, non-main header consumption,
|
||||
@@ -264,7 +269,7 @@ conversion API.
|
||||
## Source-aware application path policy
|
||||
|
||||
[`LoadNotariusPaths`](../../examples/consumers/consumers.go) is the maintained
|
||||
path-bearing example. Its application resolver uses `Resolution.InputInfo` and
|
||||
path-bearing example. Its application resolver uses `Resolution.EntryInfo` and
|
||||
`Resolution.Source` before normalizing: relative CLI input uses an explicitly
|
||||
supplied invocation directory, retained defaults use the canonical main source,
|
||||
and a file-authored scalar uses its one declaring source. Absolute paths remain
|
||||
@@ -301,10 +306,47 @@ The examples preserve domain meaning while adopting one configuration convention
|
||||
parsers translate only explicitly set configuration flags into `Override` records.
|
||||
Separate invocation state remains outside configuration.
|
||||
- Credential fields migrate to environment-name `Secret` references. Applications
|
||||
explicitly call `LoadSecretsDir` before `Load` when they choose file bootstrap;
|
||||
explicitly call `LoadSecretsIntoEnvironment` before `Load` when they choose
|
||||
file bootstrap;
|
||||
blocked empty variables remain blocked, and ordinary `Load` never changes the
|
||||
process environment.
|
||||
|
||||
### Pre-v1 public API cleanup
|
||||
|
||||
The pre-v1 API cleanup replaces these names outright; it does not retain
|
||||
compatibility aliases:
|
||||
|
||||
| Previous API | Current API |
|
||||
| --- | --- |
|
||||
| `Resolution.InputInfo(path)` | `Resolution.EntryInfo(path)` |
|
||||
| `Definition.Secret` | `Definition.Sensitive` |
|
||||
| `SourceVersionModeDefault` | `SourceVersionModeMainOnly` |
|
||||
| `SourceVersionCheck` | `SourceVersionEvidence` |
|
||||
| `SourceInfo.VersionCheck` | `SourceInfo.VersionEvidence` |
|
||||
| `ImportSelection` | `EmptyImportSelection` |
|
||||
| `SourceInfo.ImportSelections` | `SourceInfo.EmptyImportSelections` |
|
||||
| `SourceInfo.DestinationUnresolved` | `SourceInfo.DestinationIsFallback` |
|
||||
| `ImportDefaults.Follow` / `.Hidden` | `FollowSymlinks` / `IncludeHidden` |
|
||||
| `Paths(paths...)` | `SearchPaths(paths...)` |
|
||||
| `LoadSecretsDir(directory)` | `LoadSecretsIntoEnvironment(directory)` |
|
||||
| `LayerBase` | `LayerMain` |
|
||||
| `CodeExplainLimitExceeded` | `CodeHistoryLimitExceeded` |
|
||||
| `CodeResolveInvalidKind` / `CodeOptionsUnavailable` | Removed; no replacement |
|
||||
| `ImportSelection.Outcome`, `ImportSelectionOutcome`, `ImportSelectionNone` | Removed; empty-selection records no longer carry an outcome |
|
||||
| `Resolution.Record(path, ChangeDerivedDefault, reason, deps...)` | `Resolution.RecordDerivedDefault(path, reason, deps...)` |
|
||||
| `Resolution.Record(path, ChangeNormalization, reason, deps...)` | `Resolution.RecordNormalization(path, reason, deps...)` |
|
||||
| Enumerating `Result.Sources()` / `LoadError.Sources()` to find one ID | `Result.Source(id)` / `LoadError.Source(id)` |
|
||||
| Provenance string `"base"` | `"main"` |
|
||||
| History diagnostic string `"explain.limit_exceeded"` | `"history.limit_exceeded"` |
|
||||
|
||||
The YAML import keys `follow` and `hidden`, the `configkit:"secret"` tag, and
|
||||
typed `Secret` references are unchanged. Consumers that compare literal strings
|
||||
or keep serialized diagnostic/provenance expectations may need to update those
|
||||
alongside Go references. This repository guidance does not claim that downstream
|
||||
applications have migrated and does not select a release version for this
|
||||
breaking pre-v1 change. `ChangeKind` and its inspection constants remain; use
|
||||
`Default` and `Normalize` when the helper should both assign and record a value.
|
||||
|
||||
### Selected-overlay migration
|
||||
|
||||
To adopt the current selected-overlay API, rename `Options.Profile`,
|
||||
@@ -330,7 +372,7 @@ focused behavioral owner:
|
||||
| `Load`, `NoSource`, validation, versions, resolution, `SecretEnv`, overrides, and explanation | Executable examples in [`example_test.go`](../../example_test.go) |
|
||||
| Source/import/selected-overlay pipeline rules and artifact defaults | Narratio-shaped executable example and fixture |
|
||||
| Canonical module objects and dynamic option handling | WeatherReporter- and Notarius-shaped examples and migration tests |
|
||||
| `LoadSecretsDir`, bootstrap reporting, typed lookup, CLI explanation | `Example_weatherStartup` |
|
||||
| `LoadSecretsIntoEnvironment`, bootstrap reporting, typed lookup, CLI explanation | `Example_weatherStartup` |
|
||||
| Native filesystem, grouped underlays, programmatic mapping, retained resource context | `Example_nativeFilesystem`, `Example_layeredCatalog`, and their focused consumer tests |
|
||||
| Literal input destinations, root-default compatibility, and mounted peer collections | `Example_inputDestination`, `LoadCollectionBundle`, and `destinations_test.go` |
|
||||
| Named sibling inheritance, presence, and derivation | `Example_inheritedPresets` and `TestPresetCatalogOneLoadAndDerivation` |
|
||||
|
||||
Reference in New Issue
Block a user