diff --git a/docs/releases/v0.7.0.md b/docs/releases/v0.7.0.md new file mode 100644 index 0000000..a3bb0e0 --- /dev/null +++ b/docs/releases/v0.7.0.md @@ -0,0 +1,58 @@ +# ConfigKit v0.7.0 + +This minor release adds structured comparison of completed configurations. +Applications can inspect changes between two configuration files or the +effective impact of a selected overlay, with ConfigKit handling comparison and +safe value disclosure while applications own presentation. + +## Changes + +- Add `Diff[T](left, right *Result[T]) ([]Difference, error)` through the public + facade. It compares frozen effective inspection values from successful loads, + including defaults and recorded application resolution, rather than source + text or later mutations of `Result.Config`. +- Return detached changed-region records containing a semantic path, safe left + and right `ValueSnapshot` values, and `HiddenChanged`. Mappings compare + recursively, sequences report atomic changes, and records follow canonical + pointer order. Presence distinguishes additions and removals from explicit + null; equal effective values produce no records regardless of provenance or + loading history. +- Protect both snapshots with sensitivity from both loads, including historical + and dependency-derived classification. Compatible regions retain public + siblings; incompatible structural replacements use complete-region masking + where required. `HiddenChanged` identifies actual changes withheld by masking, + rather than merely indicating that a snapshot contains redacted content. +- Preserve visible public scalar changes when only historical sensitive + descendants remain, including additions and removals. Historical explanation + redaction and masking of incompatible present shapes remain intact. +- Add maintained file-comparison and base-versus-overlay examples with + consumer-owned formatting, plus an executable public API example. See the + [consumer guide](../consumers/README.md#effective-configuration-diffs) and + [configuration contract](../config.md#effective-configuration-diffs). + +## Compatibility and upgrade + +No application-code or configuration migration is required from v0.6.0. +Adopting the new API is optional. Loading, composition, inheritance, provenance, +existing inspection, and secret-handling contracts remain unchanged. + +Load both configurations successfully before calling `Diff`; nil or +uninitialized results return an error with no records. Comparison does not +reopen sources, rerun callbacks, or reread environment variables. Typed secret +references compare by configured reference name, not resolved credential bytes, +so credential rotation behind an unchanged name is not reported. Returned +snapshots describe changed regions, not cross-protected full-document context. + +Select this version and rebuild: + +```sh +go get gitea.maximumdirect.net/eric/ConfigKit@v0.7.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.3.0. 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.7.0/COPYRIGHT) | [LICENSE](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.7.0/LICENSE) | [ATTRIBUTION](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.7.0/docs/oss/attribution.md)