22 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 |
| Input destinations | Configuration contract, ADR 0011, and the destination tests below |
| Shared source-version checks | Configuration contract, ADR 0013, and the version/source-version tests below |
| 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 | Future features 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
- Check source versions with one shared policy
- 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
- Compare frozen effective configuration snapshots
- Place inputs at literal application mapping paths
- Share dependency-ready ordering
- Separate import selection controls
- Define identity and merge rules for each collection
- Apply CLI overrides after inheritance and decoding
- Keep main-file discovery explicit and composable
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 module-selected ReleaseKit publish
invocation validates the committed candidate and publishes only the intended
tag; those release checks remain distinct from the everyday development check.
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 filesystem-source and underlay roadmap, original feature request,
implementation plan, and resolved remediation record are preserved in Git history
at b604aa1 under docs/roadmap/. Current behavior belongs to the
configuration contract. Built-in sibling
inheritance is now part of the configuration contract.
The completed request, roadmap, plan, and resolved review findings are preserved
in Git history at 83c59ea under docs/roadmap/.
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.
The completed ReleaseKit adoption, startup performance request and experiments,
benchmark evidence, performance audit, implementation plan, and remediation
record are preserved in Git history at 8e91a2b under docs/roadmap/. For example:
git show 8e91a2b:docs/roadmap/startup-benchmark.md
Remaining optimization candidates belong to future performance experiments.
The completed effective-configuration diff roadmap, implementation plan, and
resolved review findings are preserved in Git history at 1c2610c under
docs/roadmap/. The
configuration contract owns current
comparison and disclosure behavior, and
ADR 0010 records the decision.
The completed input-destination, relative-import-destination, and shared
source-version roadmaps, associated consumer request, implementation plan, and
resolved review findings are preserved in Git history at e4270c9 under
docs/roadmap/. For example:
git show e4270c9:docs/roadmap/implementation.md
git show e4270c9:docs/roadmap/remediation.md
Current behavior belongs to the configuration contract's input destinations, imports, and shared source-version checks sections. Explicit sequence-item placement, collection operations, identity registration, and final registered-identity validation are owned by the strict composition section; imports owns acquisition and scheduling. The maintained sequence catalog shows the consumer boundary, and ADR 0017 records the collection decision.
The completed sequence-composition roadmap, implementation plan, and resolved
remediation record are preserved in Git history at 008d2ba under
docs/roadmap/. For example:
git show 008d2ba:docs/roadmap/sequence-composition.md
git show 008d2ba:docs/roadmap/implementation.md
git show 008d2ba:docs/roadmap/remediation.md
The completed import-discovery roadmap, implementation plan, and resolved
remediation record are preserved in Git history at 5747ec4 under
docs/roadmap/. For example:
git show 5747ec4:docs/roadmap/imports.md
git show 5747ec4:docs/roadmap/implementation.md
git show 5747ec4:docs/roadmap/remediation.md
The subsequent import-integration audit and completed remediation record are
preserved at 6903c9e:docs/roadmap/remediation.md; retrieve them with
git show 6903c9e:docs/roadmap/remediation.md.
The completed sequence-identity/collection-policy roadmap and implementation
plan are preserved in Git history at d0a605a:
git show d0a605a:docs/roadmap/sequences.md
git show d0a605a:docs/roadmap/implementation.md
Current behavior belongs to the configuration contract's
strict composition,
sibling inheritance, and
CLI overrides sections.
The completed remediation record, including the algorithm-audit findings, is
preserved at ea46001:docs/roadmap/remediation.md.
The completed configuration-discovery roadmap, implementation plan, and
remediation record are preserved in Git history at 0369111, for example
git show 0369111:docs/roadmap/remediation.md. Current behavior belongs to
configuration discovery; the public
discovery declarations own the Go API.
The completed consolidation proposal, implementation plan, and resolved audit
findings are preserved in Git history at 34cbc0d under docs/roadmap/. For
example:
git show 34cbc0d:docs/roadmap/implementation.md
git show 34cbc0d:docs/roadmap/remediation.md
Potential enhancements are tracked in future features.
Install the Go version required by go.mod or a compatible newer 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 release procedure performs
its selected validation through one publish invocation. The everyday checker
remains a development gate and is not a separate release prerequisite. 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 | Import internals, source acquisition, FIFO, import traversal, import evidence, relative destinations, globs | go test ./internal/engine -run 'Source|Import|Glob|Filesystem|Nonregular|RegularFile' |
| Explicit main-file discovery and absent-input loading | Candidate selection, load integration, public facade, and maintained catalog and preset examples | `go test ./internal/engine -run 'Discovery |
| Import defaults, empty-selection evidence, and dependency-ready ordering | Defaults and facade evidence, engine import evidence, scheduler, scheduling integrations | `go test ./internal/engine -run 'Import |
| Native filesystem and mapping sources | Native acquisition, filesystem facade, mapping facade | go test ./internal/engine -run 'NativeFilesystem' and go test . -run 'TestFacade' |
| Composition, selected overlays, CLI precedence | Composition, overlay, selected overlays, overrides | go test ./internal/engine -run 'Compose|Overlay|Override' |
| Sequence identity, declarations, and operations | Identity, registrations, declarations, combination, final facade validation, and consumer catalog | go test ./internal/engine -run 'Sequence|Collection', go test . -run 'SequenceIdentity|SequenceRegistration', and go test ./examples/consumers |
| Sibling inheritance, provenance, history, sensitivity | Implementation flow, expansion, destination scopes, origins, history, secrets, public loading | go test ./internal/engine -run 'Inheritance|Inherited' and go test . -run '^TestFacadeInheritance|^TestFacadeInheritedSecrets' |
| Layered loading and source equivalence | Grouped lifecycle, layered facade, equivalence | go test ./internal/engine -run '^TestGrouped', go test . -run '^TestFacadeLayered', and go test . -run '^TestEquivalentSourceForms' |
| Input and relative-import destinations, mounted sources, and source ownership | Destination engine tests, tier tests, import traversal and version tests, accounting tests, lifecycle inspection tests, public source/error tests, resource contexts, and consumer examples | `go test ./internal/engine -run 'Destination |
| Shared source-version modes and evidence | Engine source-version tests, public facade tests, and consumer example tests | go test ./internal/engine -run 'SourceVersion', go test . -run 'SourceVersion', and go test ./examples/consumers |
| Schema, defaults, projection, cloning | Implementation flow, schema, decoding, projection and typed cloning | 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' |
| Passive resource contexts | Engine contexts, public contexts | go test ./internal/engine -run 'Resource' and go test . -run 'SourceContext' |
| Secrets, bootstrap, redaction, explanation | References, bootstrap, rendering, explanation | go test ./internal/engine -run 'Secret|Bootstrap|Effective|Explain|Explanation|History|Sensitivity' |
| Effective configuration diff | Engine comparison and masking tests, engine operation tests, root facade tests, and consumer examples | `go test ./internal/engine -run 'Diff |
| Consumer examples and migration fixtures | Consumer tests, native, layered, and ordinary relative-import examples, mounted collection examples, API examples | go test ./examples/consumers and go test . -run '^Example' |
| Assembly and layered scaling evidence | Assembly benchmarks, layered benchmarks | go test ./internal/engine -run '^$' -bench '^BenchmarkUnderlay' -benchmem; repeat with ^BenchmarkCompose and ^BenchmarkOverlay |
| Identified-sequence scaling evidence | Mixed-upsert benchmark | go test ./internal/engine -run '^$' -bench '^BenchmarkSequenceMixedUpsert$' -benchmem |
| Inheritance scaling evidence | Expansion benchmarks | go test ./internal/engine -run '^$' -bench '^BenchmarkInheritance' -benchmem |
| Documentation links and dependency isolation | Link checks, import boundary, public boundary | go test . -run 'TestLocalDocumentationLinks|TestDependencyImportBoundary|TestPublicFacadeBoundary' |
| Development check behavior | Development checker test | go test . -run '^TestDevelopmentCheckHandlesFilenamesAndStopsOnFailure$' |
| Release profile wiring | Release profile test | go test . -run '^TestReleaseKitProfile$' |
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