8.6 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.
- Read the architecture policy for code or design work.
- Read the policy, contract, and internal documents applicable to the task.
- Inspect the relevant implementation and behavioral tests before changing them.
Task-specific reading guide
| Task | Read |
|---|---|
| Repository orientation or component responsibility | Architecture policy and component overview |
| Documentation changes | Documentation policy and the owning document |
| Architecture decisions or future work | Documentation policy, deferred scope, and relevant ADRs listed below |
| Code and test changes | Architecture policy, testing policy, and the owning contract and tests from the map below |
| Examples or copyable assets | The owning implemented contract and consumer adoption guide |
| Release preparation | Release policy and 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.
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 during resolution record
links to the current contract and evidence. Its completed implementation handoffs
are preserved at 28e7fc5:docs/roadmap/implementation.md; inspect them with
git show 28e7fc5:docs/roadmap/implementation.md until release preparation
retires the completed roadmap material.
Baseline validation
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 separate release checker adds
two-toolchain, module-hygiene, race, and cross-build gates.
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, profiles, CLI precedence | Composition, overlay, profiles, overrides | go test ./internal/engine -run 'Compose|Overlay|Profile|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 | `go test . -run 'TestLocalDocumentationLinks |
| Check-command behavior | Shell regression | go test . -run '^TestCheckScripts' |
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
| | Check-command behavior | [Shell regression](../release_check_test.go) |go test . -run '^TestCheckScripts'` |
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