ConfigKit/docs/releases/v0.10.0.md

ConfigKit v0.10.0

This minor release adds explicit, composable discovery of a configuration file. Applications choose the search conventions and their order; ConfigKit selects one file during loading and returns the final configuration with its normal metadata. Optional searches that find no file share the expanded NoSource() lifecycle.

Changes

• Add SearchConfig, immutable Search and FilenameGroup descriptions, and search-wide requiredness through SearchOptions. Compose explicit Paths, custom SearchDirectory descriptions, and built-in Unix system, user-config, home, or working-directory presets with Searches. See the public declarations and discovery contract.
• Expand searches in supplied order, trying a directory's filename groups before moving to the next directory. Named and generic groups provide conventional YAML filenames; custom groups provide literal names. Directory searches distinguish omitted filename selection from an explicitly empty selection. Constructors perform no filesystem access, and each load observes current directory bases and file availability.
• Select the first existing candidate. Access errors and failures while loading the selected file terminate the load rather than trying another configuration. Selected files retain physical source identity, placement, provenance, imports, and relative-resource context. Discovery works with ordinary loading and layered inputs, including underlays, without adding a precedence tier.
• Permit enabled imports with an absent main input: there are no main import declarations to traverse, while actual underlay sources retain normal imports. Support ordinary selected overlays with an absent main and explicit filesystem context, including a root-only host context. Layered overlays retain their independent OverlayFilesystem requirement. See single-source loading and layered loading.
• Preserve ordinary file-context behavior after discovery and include the failing candidate's file identity in access diagnostics. Use Go's platform-aware Windows component rules and native drive-root-relative path resolution. Isolate user-config tests according to the host Go conventions.

Compatibility and upgrade

Existing explicit source constructors and loading APIs remain available. File(path) remains an exclusive selection that fails for a missing file; discovery is activated only by explicitly supplying SearchConfig.

Searches are optional by default. Set SearchOptions{Required: true} when the application must find a file. An exhausted optional search contributes no main document or source record; application version checks, defaults, resolution, and validation still run under their existing rules and may reject incomplete configuration. A selected overlay is still required to exist.

The former NoSource() rejections of enabled imports and explicit filesystem context are relaxed. An active ordinary overlay with no main file now loads when explicit context is supplied. Applications that relied on those combinations being rejected should review their option handling. Selected host files derive their own base directory; do not supply an explicit BaseDir or native filesystem context for a search that selects a host file.

Applications may replace their own fallback-loading loops with the new search descriptions. The maintained consumer examples show simple preset selection and custom-first discovery alongside existing configuration tiers. Composition, collection operations, inheritance, CLI precedence, and the complete-on-return ownership model retain their existing semantics.

Select this version and rebuild:

go get gitea.maximumdirect.net/eric/ConfigKit@v0.10.0

The consumer minimum remains Go 1.26.0. Release validation uses Go 1.26.10. The YAML dependency remains go.yaml.in/yaml/v4 v4.0.0-rc.6, and the maintainer tool remains ReleaseKit v0.4.1. Linux amd64 and arm64 remain release-validated targets; macOS remains best-effort. Publication follows the existing release procedure.

COPYRIGHT | LICENSE | ATTRIBUTION