From 48c50e49d73a3eb770593f491f76a1e079ab4136 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Mon, 2 Nov 2026 01:05:49 +0000 Subject: [PATCH] Write the version 1.0.0 release notes --- docs/releases/v1.0.0.md | 143 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 143 insertions(+) create mode 100644 docs/releases/v1.0.0.md diff --git a/docs/releases/v1.0.0.md b/docs/releases/v1.0.0.md new file mode 100644 index 0000000..2f0f6cc --- /dev/null +++ b/docs/releases/v1.0.0.md @@ -0,0 +1,143 @@ +# ConfigKit v1.0.0 + +ConfigKit's first stable release completes the public API cleanup, moves the Go +module to `go.maximumdirect.net/configkit`, and scopes configuration controls to +the root of each source document. It also corrects presence, history, and +sensitivity reporting and adds direct source lookup for successful and failed +loads. + +This release includes intentional breaking changes from v0.10.2. The public Go +API, documented configuration and resolution semantics, and structured diagnostic +contracts now follow the [stable-release compatibility policy](../policy/release.md#versioning-and-compatibility). +That policy includes the existing allowance for minor releases to raise the Go +consumer minimum. + +## Upgrade from v0.10.2 + +### Module path + +Update the dependency requirement and Go imports from +`gitea.maximumdirect.net/eric/ConfigKit` to `go.maximumdirect.net/configkit`, +selecting v1.0.0. The package name remains `configkit`. + +Go treats the two import paths as different packages with different named types. +Coordinate the change with dependencies that exchange ConfigKit values with your +application. Earlier tags retain their original module declarations; no old-path +compatibility module is provided. See the +[module migration guide](../consumers/README.md#vanity-module-path-migration). + +### Source-document controls + +Rename genuine source-root `configkit` control blocks to `config` in main files, +imported fragments, underlays, selected overlays, and programmatic mapping inputs. +The recognized controls remain `imports` and `sequences`, subject to their +existing context-specific rules and import opt-in. + +The control name is reserved only at the root of each acquired document. ConfigKit +extracts controls before placing that document's payload. Nested `config` keys, +including those in sequence records, are ordinary application data. Application-root +`config` data produced by placement, defaults, CLI overrides, or resolution is +also ordinary data and is not interpreted again as controls. + +Review source-root application fields already named `config`: move, rename, or +separately mount that data. The former names `configkit` and `_configkit` are now +ordinary application keys at every depth, with no control aliases. A permissive +schema can therefore accept an unmigrated control block as data without executing +its imports. Stored source-local declaration paths change from `/configkit/...` +to `/config/...`. + +Source-version checks distinguish actual source-local controls from application +paths with the same spelling. Existing inheritance rules remain in place. See +[imports and control scope](../config.md#declaration-and-selection-rules) and +[the directive migration guidance](../config.md#earlier-directive-spelling). + +### Public Go API + +The following names replace their pre-v1 counterparts outright, without +compatibility aliases: + +| Previous API | v1.0.0 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` | +| `Resolution.Record(path, ChangeDerivedDefault, reason, deps...)` | `Resolution.RecordDerivedDefault(path, reason, deps...)` | +| `Resolution.Record(path, ChangeNormalization, reason, deps...)` | `Resolution.RecordNormalization(path, reason, deps...)` | + +The recording methods describe mutations the application has already performed; +they do not assign values. `Default` and `Normalize` remain the helpers that both +assign and record. `EntryInfo` names the fixed resolution-entry metadata view, +including defaults and CLI assignments. Version evidence records what was +observed, not proof of checker execution or acceptance. + +The redundant `ImportSelection.Outcome`, `ImportSelectionOutcome`, and +`ImportSelectionNone` are removed. Empty-selection records retain their selector, +path, and location. The obsolete diagnostic constants `CodeResolveInvalidKind` +and `CodeOptionsUnavailable` are also removed without replacements. + +Update stored or compared strings as well as Go symbols: + +- The main provenance layer changes from `"base"` to `"main"`. +- The retained-history limit diagnostic changes from + `"explain.limit_exceeded"` to `"history.limit_exceeded"`. + +The YAML import options `follow` and `hidden`, the `configkit:"secret"` Go tag, +and typed `Secret` references retain their existing spelling and behavior. See +the [API migration guide](../consumers/README.md#pre-v1-public-api-cleanup) for +the consolidated mapping and usage guidance. Rebuild and run your application's +configuration tests after migrating its imports, API calls, and source controls. + +## Source inspection + +`Result.Source(id)` and `LoadError.Source(id)` return a detached `SourceInfo` +record and a found flag for an already acquired source. They complement +`Sources()` and the existing callback-scoped `Resolution.Source(id)`. Empty or +unknown IDs return false. Lookup does not reopen inputs or resolve credentials; +failed loads retain the same partial, conservatively redacted evidence as their +source inventory. See [results and failures](../config.md#results-and-failures). + +## Correctness and internal improvements + +- Resolution presence queries distinguish numeric mapping keys from sequence + indexes using the configuration's entry shape. A later shape change no longer + transfers input explicitness to a different semantic path. +- Metadata history and value explanations now use one shared internal history + model. This corrects attribution across shape changes, preserves container + origins, and avoids duplicate intermediate source-history records. +- Final dynamically typed secret fields retain their sensitivity classification + in inspection output. Parsed dependency paths are deduplicated without losing + distinctions needed for sensitivity propagation. +- Composition-conflict diagnostics preserve claimant order through structured + reporting and rendering, consistent with scoped assembly order. +- History selection and explanation use indexes and reuse prepared selections + and sensitivity dependencies to reduce repeated traversal. Retained-history + accounting follows the shared model, and secret resolution and validation share + traversal machinery. + +These changes preserve the documented loading and inspection rules apart from +the explicit migrations above. No end-to-end performance improvement is claimed. +The [configuration contract](../config.md) and public Go declaration comments +remain the behavior references. + +## Requirements and release delivery + +The consumer minimum remains Go 1.26.0, and the YAML dependency is unchanged. +Linux amd64 and arm64 remain the release-validated targets; macOS support remains +best-effort under the [platform support policy](../policy/release.md#platform-support). + +Release tooling moves to `go.maximumdirect.net/releasekit` v0.6.0. Beginning with +this release, the source tag and checked-in note are accompanied by a Gitea release +page containing the complete note and licensing footer. Source publication and +hosted delivery remain separate outcomes under the [release procedure](../release.md). + +[COPYRIGHT](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.0.0/COPYRIGHT) | [LICENSE](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.0.0/LICENSE) | [ATTRIBUTION](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.0.0/docs/oss/attribution.md)