diff --git a/docs/policy/architecture.md b/docs/policy/architecture.md index 1d7bd34..5121fdd 100644 --- a/docs/policy/architecture.md +++ b/docs/policy/architecture.md @@ -2,7 +2,7 @@ **Base Policy Version:** 1.3 -**Last Updated**: 2026-10-16 +**Last Updated**: 2026-10-18 **Upstream Source:** [Standard Repository Policies](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/architecture.md) @@ -91,6 +91,48 @@ boundaries, and keep simple consumers independent of optional composition features. The [consumer adoption guide](../consumers/README.md) demonstrates the implemented surface against representative simple and complex shapes. +## Simplicity, Defaults, And Explicit Controls + +These principles apply throughout ConfigKit: to configuration syntax, the public +Go API, defaults, and feature design. Evaluate their effects on both configuration +authors and consuming applications. + +**Keep straightforward workflows straightforward.** Common configuration +workflows should require little configuration text and minimal API setup. +Support more demanding workflows through explicit, composable options, without +requiring simple consumers to understand or configure those options. + +**Prefer simple, permissive defaults with explicit controls.** Choose predictable +defaults that minimize required setup and accommodate valid configurations +without unnecessary restrictions. Provide selectable options for workflows that +need additional capabilities, narrower behavior, or stronger requirements. + +Measure simplicity by what consumers must understand and maintain, including +configuration text and application-side plumbing. Concise syntax is useful, but +hidden inference and interacting meanings can make a shorter declaration harder +to understand. Prefer explicitness where it makes behavior more predictable. +A terse configuration format that requires substantial application-side +infrastructure does not satisfy the simplicity principle. + +Define what permissiveness means for each behavior. Allowing an optional +contribution to be absent or accepting valid inputs without an unnecessary +filename restriction can reduce required setup. Invalid declarations, ambiguous +composition, and unreadable selected sources must still produce meaningful +errors under the applicable contracts. Permissiveness does not authorize silent +recovery from invalid supplied configuration or weaken configuration integrity. + +Options should express coherent choices with understandable purposes and fit +ConfigKit's shared configuration model. Support powerful controls when they +serve concrete needs; these principles do not require a switch for every +implementation behavior or conceivable consumer preference. + +Defaults require judgment when simplicity and permissiveness pull in different +directions. Broader discovery can accommodate more layouts while increasing the +implicit search scope. Evaluate such tradeoffs explicitly; these principles do +not mechanically select the broadest behavior for every option. Changes to +existing defaults remain subject to compatibility review, and proposed behavior +remains in the roadmap until implemented. + ## Responsibility Boundaries ConfigKit owns configuration input processing and the coordination of decoding,