base-layer/configkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 2 Wiki Activity

Make consumer documentation easier to follow

Browse Source
This commit is contained in:
Eric Rakestraw
2026-11-01 19:04:48 +00:00
parent e74c26a4b3
commit 6db441893d
12 changed files with 1065 additions and 399 deletions
Download Patch File Download Diff File Expand all files Collapse all files

62
docs/roadmap/documentation.md
View File

@@ -2,10 +2,34 @@
Reviewed revision: `08bb3a20c6a565646d98f68688d268c7bae39573`.
Status: proposed revisions only. This catalog identifies opportunities to make
existing documentation easier to understand. None of the proposals has been
applied to its target page. The previous consistency audit remains in Git
history; its two findings were corrected in `94d1e33`.
Status: complete. All D01–D18 revisions have been applied and reviewed together
for consistency. The catalog below preserves the proposals that guided the
work; the completion record identifies their implemented locations. The previous
consistency audit remains in Git history; its two findings were corrected in
`94d1e33`.
## Completion record
| Proposal | Implemented result |
| --- | --- |
| D01 | [README](../../README.md) leads with the loading outcome and minimal example, followed by optional tasks and platform/licensing links. |
| D02 | [Consumer guide](../consumers/README.md) starts with task routes, defaults, validation, and inspection; example background and the test inventory follow usage. |
| D03 | [Reference introduction](../config.md) supplies topic routes, YAML illustrations, path definitions, and common-versus-detailed subheadings. |
| D04 | [Sources](../config.md#sources), [results](../config.md#results-and-failures), and [resource lifetime](../config.md#completion-and-resource-lifetime) explain copying, reuse, saved inspection, and caller-owned resources. |
| D05 | [Priority](../config.md#priority-and-processing-order), [strict combination](../config.md#combining-mappings), and [defaults](../config.md#defaults-and-typed-decoding) have visible examples and retain collection exceptions. |
| D06 | [Discovery](../config.md#configuration-discovery) shows the four attempted paths and distinguishes optional absence, required absence, and selected-file failure. |
| D07 | [Imports](../config.md#explicit-imports) introduce the three selectors, option applicability, requiredness, ordering, and earlier syntax separately. |
| D08 | [Placement](../config.md#input-destinations) illustrates files and assembled YAML; [contexts](../config.md#source-resource-contexts) explain later resource access and ownership. |
| D09 | [Identified lists](../config.md#identified-lists-a-worked-example) show replace, append, and whole-record upsert before registration and policy-lifetime details. |
| D10 | [Inheritance](../config.md#sibling-inheritance) starts with parent/child settings, then cancellation and identified records before exact scheduling rules. |
| D11 | [Versions](../config.md#application-schema-versions) introduce application acceptance, a mode table, mounted headers, and the limits of observed evidence. |
| D12 | [Callbacks](../config.md#recorded-application-resolution) have task and helper tables, a derived-default example, and entry-state/lifetime guidance. |
| D13 | [Secrets](../config.md#typed-secret-references) separate lookup, hiding, and bootstrap; [bootstrap](../config.md#explicit-secrets-directory-bootstrap) explains empty existing variables and partial reports. |
| D14 | [Inspection](../config.md#layered-metadata) starts with reader needs and a default/main/overlay example; [diffs](../config.md#effective-configuration-diffs) explain snapshot flags and hidden changes. |
| D15 | [YAML](../config.md#yaml-documents), [defaults](../config.md#defaults-and-typed-decoding), [projection](../config.md#typed-projection-and-ownership), and [failures](../config.md#safe-failures) have practical examples; descriptor caching moved to the [internal overview](../internal/overview.md). |
| D16 | [Package documentation](../../doc.go) and the targeted public declarations explain purpose, paths, returned copies, and saved state while retaining precise contracts. |
| D17 | [Migration guidance](../consumers/README.md#intentional-migration-changes) leads with numbered consumer actions and explains package type identity alongside the retained old/new table. |
| D18 | [Release procedure](../release.md) defines operational terms and explains Go selection, publication statuses, and tag-object recovery without changing command blocks or gates. |
## Audience and Scope
@@ -400,14 +424,34 @@ The highest-impact starting points are the README and consumer entry routes
(D13–D14). The other proposals develop a selected task or reference topic. These
priorities are editorial recommendations, not additional release gates.
Later rewrites should preserve existing contracts, diagnostic identifiers,
These revisions preserve existing contracts, diagnostic identifiers,
defaults, limits, security boundaries, and exceptions. Keep precise material
available after its plain-language introduction. A simpler explanation must not
imply universal last-value replacement, universal null support, transactional
loading, refreshed inspection after caller mutation, or stronger filesystem
isolation.
This pass changes only this catalog. No user-facing page, Go comment, example,
policy, command, test, or implementation has been revised. Later implementation
can validate changed examples and commands at their existing owners and inspect
rendered tables and navigation under the documentation policy.
Implementation changes consumer-facing prose and Go declaration comments, with
the relocated descriptor-caching explanation in the existing internal overview.
Policies, accepted ADRs, release history, license notices, dependencies, and
production behavior remain unchanged. Validation includes exercising the revised
illustrations against the library, checking local links and Markdown tables,
comparing Go tokens to confirm comment-only edits, and verifying that release
command blocks remain identical to the implementation baseline `e74c26a`.
Completed validation with Go 1.26.10 and dependency downloads disabled:
- `./scripts/check.sh` passed formatting, whitespace, all tests (including local
links and executable examples), vet, and build.
- Temporary programs outside the repository exercised the revised README,
callbacks, YAML, discovery, imports, collection operations, placement,
inheritance, version modes, inspection, secret bootstrap, defaults, and
projection illustrations against the current library; all passed.
- A Go scanner comparison confirmed identical non-comment tokens in all six
changed Go files. All 12 release command blocks are byte-for-byte unchanged.
- The six affected Markdown pages rendered successfully with the project's
Markdown parser; all 27 tables have consistent column counts. Existing
navigation anchors remain available.
The final consistency pass checked terminology, worked results, public comments,
cross-page links, documentation ownership, and the preserved release workflow.