112 lines
6.7 KiB
Markdown
112 lines
6.7 KiB
Markdown
# ConfigKit v0.9.0
|
|
|
|
This minor release expands import selection, adds author-declared collection
|
|
identity and operations, and supports inheritance between identified records.
|
|
It also moves CLI assignments after inheritance and typed decoding. These changes
|
|
include breaking API and configuration behavior changes from v0.8.0; review the
|
|
migration guidance below before upgrading.
|
|
|
|
## Changes
|
|
|
|
- Extend imports with named-file and directory lists, directory filename patterns,
|
|
exclusions, recursion and depth controls, and explicit hidden-file and symlink
|
|
discovery controls. Add `ImportDefaults` to ordinary and layered options, with
|
|
authored declarations taking precedence over application defaults. Imports are
|
|
optional by default. `SourceInfo.ImportSelections` exposes completed optional
|
|
declarations that selected no sources. See the
|
|
[import contract](../config.md#explicit-imports) and
|
|
[consumer guidance](../consumers/README.md#import-defaults-and-selection-inspection).
|
|
- Use shared dependency-ready ordering for import composition and sibling
|
|
inheritance. Dependencies complete before dependents, with deterministic
|
|
selection among currently eligible contributions. Source acquisition and
|
|
callback order remain separate from assembly order. See the
|
|
[ordering decision](../adr/0015-shared-dependency-ready-ordering.md).
|
|
- Add root `configkit.sequences` declarations for collection identity and
|
|
`replace`, `append`, or `upsert` operations, including in selected overlays.
|
|
Strict peers combine distinct identities and reject duplicates; precedence
|
|
and inheritance apply the destination's collection operation. Upsert replaces
|
|
a whole matching record at its retained position. Identity supports compound
|
|
field sets and scalar strings, numbers, booleans, and null. See the
|
|
[collection contract](../config.md#strict-document-composition).
|
|
- Add `Definition.SequenceIdentities`, exact `SequenceIdentityAt` registrations,
|
|
and dynamic `SequenceIdentityMatching` selectors. Application registrations
|
|
govern structural collection operations and check existing matching final
|
|
typed sequences, including values from defaults, CLI assignments, and
|
|
application resolution. YAML-only declarations govern structural operations
|
|
without adding that final-result check.
|
|
- Support record inheritance within an identified sequence using an `extends`
|
|
mapping containing the parent's complete identity. The child retains its own
|
|
identity, relationships use surviving assembled records, and output sequence
|
|
order is preserved. See [sibling inheritance](../config.md#sibling-inheritance)
|
|
and the maintained [sequence catalog](../consumers/README.md#identified-prompt-sequences).
|
|
- Apply explicit CLI overrides to the decoded configuration before application
|
|
resolution. Mappings retain omitted fields and their presence metadata;
|
|
sequences replace whole lists independently of collection operations. See the
|
|
[CLI contract](../config.md#explicit-cli-overrides).
|
|
- Correct native import alias and contained-symlink handling, source-version
|
|
path projection, and provenance/history through collection movement,
|
|
replacement, inheritance, and CLI assignment. Reduce repeated scans,
|
|
accumulated policy copying, and sparse-projection storage during construction.
|
|
|
|
## Compatibility and upgrade
|
|
|
|
This pre-v1 minor release intentionally changes the v0.8.0 contracts:
|
|
|
|
1. **Migrate import requiredness.** The YAML `optional` field is removed and is
|
|
rejected. Replace `optional: true` with `required: false`; omission is equivalent
|
|
when the application does not default imports to required. Replace
|
|
`optional: false` with `required: true`. Imports that previously relied on
|
|
implicit requiredness now need `required: true`, or an application
|
|
`ImportDefaults.Required` default set to true. Review discovery filters:
|
|
`follow` and `hidden` default to true, and directory searches select all
|
|
filenames unless a pattern is supplied.
|
|
2. **Replace sequence registrations.** `SequenceComposition` and
|
|
`Definition.SequenceCompositions` are removed without compatibility aliases.
|
|
For a previous registration at `prompts` using `id`, use:
|
|
|
|
```go
|
|
rules.SequenceIdentities = []configkit.SequenceIdentity{
|
|
configkit.SequenceIdentityAt(configkit.Keys("prompts"), "id"),
|
|
}
|
|
```
|
|
|
|
These registrations now also enforce identity in final typed sequences. Fix
|
|
missing or duplicate identities introduced by defaults, CLI assignments, or
|
|
application resolution. Registration does not require a collection to exist
|
|
or determine its allowed shape; schema and application validation retain
|
|
those responsibilities.
|
|
3. **Review collection precedence and ordering.** An identified collection now
|
|
defaults to upsert across layers and inheritance when no explicit mode
|
|
applies, rather than unconditional whole-sequence replacement. Declare
|
|
`mode: replace` at the relevant destination where replacement is intended.
|
|
With append or upsert, `[]` contributes no records and does not clear the
|
|
collection; null is invalid. Use `mode: replace` with `[]` to clear it.
|
|
An explicit mode persists at its destination until changed; a parent's mode
|
|
does not transfer to a different inheriting destination. Unidentified
|
|
sequences retain strict peer conflicts and whole-value precedence
|
|
replacement. Dependency-ready assembly can change sequence positions and
|
|
diagnostic or history order compared with the former traversal order.
|
|
4. **Review CLI recovery and inheritance assumptions.** CLI overrides can no
|
|
longer repair values that fail earlier decoding, bypass source or inheritance
|
|
errors, or add or cancel inheritance relationships. Supply structural
|
|
directives in source configuration. Application resolution still receives
|
|
explicit CLI values and may record subsequent normalization or derivation.
|
|
5. **Update affected Go literals and diagnostic handling.** Use keyed literals
|
|
for expanded option and source-information structs. Collection validation adds
|
|
`CodeSequenceInvalid` (`sequence.invalid`) and `CodeSequenceConflict`
|
|
(`sequence.conflict`); update diagnostic handling where applicable.
|
|
|
|
Select this version and rebuild:
|
|
|
|
```sh
|
|
go get gitea.maximumdirect.net/eric/ConfigKit@v0.9.0
|
|
```
|
|
|
|
The consumer minimum remains Go 1.26.0. The YAML dependency remains
|
|
`go.yaml.in/yaml/v4 v4.0.0-rc.6`, and the maintainer tool dependency remains
|
|
ReleaseKit v0.4.1. Linux amd64 and arm64 remain release-validated targets;
|
|
macOS remains best-effort. Publication follows the existing
|
|
[release procedure](../release.md).
|
|
|
|
[COPYRIGHT](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.9.0/COPYRIGHT) | [LICENSE](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.9.0/LICENSE) | [ATTRIBUTION](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.9.0/docs/oss/attribution.md)
|