From b3ec860fac74d61a14b14ee3ab632459618ee822 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sat, 24 Oct 2026 14:44:58 +0000 Subject: [PATCH] Document the ConfigKit v0.9.0 release --- docs/releases/v0.9.0.md | 108 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 108 insertions(+) create mode 100644 docs/releases/v0.9.0.md diff --git a/docs/releases/v0.9.0.md b/docs/releases/v0.9.0.md new file mode 100644 index 0000000..8d16aaf --- /dev/null +++ b/docs/releases/v0.9.0.md @@ -0,0 +1,108 @@ +# 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` or omit it; 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. + 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)