10 KiB
Development
Start here when contributing to ConfigKit. Read the task-specific owners below before making changes. The component overview maps implementation responsibilities; the configuration contract owns public behavior.
Initial orientation
- Inspect the working tree and preserve unrelated changes.
- Use the Policy Reading Guide below to select applicable policies.
- Read the contract and internal documents applicable to the task.
- Inspect the relevant implementation and behavioral tests before changing them.
Policy Reading Guide
| Policy | Read before… |
|---|---|
| Policy set provenance | Adopting policies, checking upstream revisions, or updating the adopted policy set. |
| Agents | Recommending, planning, or implementing repository changes. |
| Architecture | Planning or changing Go library code or its structure. |
| Testing | Selecting validation for code changes, or adding, changing, removing, or evaluating tests. |
| Documentation | Writing, revising, or reorganizing documentation. |
| OSS | Adding or updating dependencies or incorporated third-party material, or changing licensing or attribution. |
| Release | Preparing or publishing a release, changing release procedures, or making versioning and compatibility decisions. |
- Read applicable policies before making decisions they govern; multiple policies may apply.
- Select policies using the task triggers above. Follow cross-references to relevant sections when needed to resolve a concrete question.
- Reuse policies already available in context; reread when changed or no longer available.
- Expand reading when the task's scope expands.
- When revising a policy itself, read that policy and any provisions elsewhere affected by the revision.
Task-specific reading guide
| Task | Read |
|---|---|
| Repository orientation or component responsibility | Component overview |
| Documentation changes | The owning document |
| Licensing, dependencies, attribution, or release-document changes | Project grant and attribution; release changes also follow the release procedure |
| Architecture decisions or future work | Deferred scope and relevant ADRs listed below |
| Code and test changes | The owning contract and tests from the map below |
| Examples or copyable assets | The owning implemented contract and consumer adoption guide |
| Release preparation | Release procedure |
Accepted decisions:
- Separate composition and overlay
- Own YAML semantics behind a private parser boundary
- Preserve presence and record application resolution
- Secret references and explicit bootstrap
- Explicit overrides and safe explanation
- Keep the public facade root-owned
For cross-cutting changes, follow every applicable row. Completed implementation
and remediation plans are preserved in Git history at cb5b435; use current
contracts and the component overview for ongoing work. For example:
git show cb5b435:docs/roadmap/remediation.md
Release-candidate, publication, and verification work follows the operational release procedure. Its single publication command validates the committed candidate and publishes only the intended refs.
The completed string-and-integer schema-version implementation and remediation
records are preserved in Git history at 244104f. The
configuration contract owns current behavior.
The completed source-origins and public-facade roadmaps, implementation plan, and
resolved review findings are preserved in Git history at 5760614, for example
git show 5760614:docs/roadmap/remediation.md. The earlier source-origins staged
plan remains at 28e7fc5:docs/roadmap/implementation.md. Current resolution
behavior belongs to the configuration contract,
and current facade ownership belongs to the component overview.
Baseline validation
The completed overlay rename plan and release-workflow simplification record are
preserved in Git history at 73ce6e9 under docs/roadmap/. Current overlay
behavior belongs to the configuration contract,
and release operations belong to the release procedure.
Install Go 1.25.0 or a supported patched/newer Go toolchain. Acquire declared dependencies explicitly before entering an offline development or validation environment:
go mod download
Run the everyday check with Bash 3.2 or newer and Git:
./scripts/check.sh
The script runs from the repository root regardless of the
invocation directory. It checks Go formatting without rewriting files, checks
staged/unstaged and untracked whitespace, then runs go test ./...,
go vet ./..., and go build ./..., stopping on the first failure. It uses the
installed Go toolchain by default, honors an explicit GOTOOLCHAIN, and disables
dependency downloads. Acquire dependencies and any selected toolchain beforehand.
Format reported Go files with gofmt -w <files>.
The default suite includes executable examples, maintained consumer fixtures, local documentation-link checks, and the dependency import-boundary check. It must stay deterministic and runnable without network access or credentials. Still inspect new/untracked content and review paths, examples, ownership, and current-versus-planned claims; automated checks do not replace content review.
Use focused checks while iterating, with validation proportionate to the change
under the testing policy. Documentation-only work normally needs the local-link
check below and whitespace review; behavior-bearing examples and commands also
need execution. Use go test -race ./... for ownership or concurrency changes.
The publication command invokes
the release checker once. It performs one minimum-toolchain offline race-suite
run, one full vet pass, and Linux cross-builds using readonly module mode.
It already covers examples, links, and package boundaries; do not additionally
run the everyday checker just to repeat those checks. CI never gates a release.
Task-to-test map
Commands run from the repository root after dependency acquisition. These are starting points for focused iteration; run the everyday check before handing off code changes. Use the component overview to find the corresponding implementation.
| Task | Behavioral test owners | Focused command |
|---|---|---|
| YAML syntax, diagnostics, parser limits | Adapter tests, source translation | go test ./internal/yaml and go test ./internal/engine -run '^TestParseSource' |
| File/reader access, imports, globs, containment | Sources, FIFO, imports, globs | go test ./internal/engine -run 'Source|Import|Glob|Filesystem|Nonregular|RegularFile' |
| Composition, selected overlays, CLI precedence | Composition, overlay, selected overlays, overrides | go test ./internal/engine -run 'Compose|Overlay|Override' |
| Schema, defaults, projection, cloning | Schema, decoding, projection | go test ./internal/engine -run 'Schema|Decode|Projection|Clone|Inline|CompareDocument' |
| Lifecycle, resolution, validation, callback ownership | Loading, resolution, validation, ownership, independence | go test ./internal/engine -run 'Load|Resolution|Validation|Validator|Hook|Callback|Parallel' |
| Paths, metadata, provenance | Paths, metadata, provenance | go test ./internal/engine -run 'Path|Metadata|Provenance|Queries' |
| Secrets, bootstrap, redaction, explanation | References, bootstrap, rendering, explanation | go test ./internal/engine -run 'Secret|Bootstrap|Effective|Explain|Explanation|History|Sensitivity' |
| Consumer examples and migration fixtures | Consumer tests, API examples | go test ./examples/consumers and go test . -run '^Example' |
| Documentation links and dependency isolation | Link checks, import boundary, public boundary | go test . -run 'TestLocalDocumentationLinks|TestDependencyImportBoundary|TestPublicFacadeBoundary' |
| Development and release checker behavior | Shell regression | go test . -run 'TestCheckScripts|TestDevelopmentCheck' |
| Guarded release publication and recovery | Publication regression | go test . -run '^TestReleasePublication' |
Fuzz validation
Run the bounded fuzz targets independently from the repository root. These exact commands keep each campaign short and constrain concurrent workers:
go test ./internal/engine -run='^$' -fuzz='^FuzzParsePath$' -fuzztime=30s -parallel=2
go test ./internal/yaml -run='^$' -fuzz='^FuzzParseDocument$' -fuzztime=30s -parallel=2
go test ./internal/engine -run='^$' -fuzz='^FuzzCompositionAndOverlay$' -fuzztime=30s -parallel=2