2026-09-06 10:52:38 -05:00
# Development
2026-09-07 01:40:39 +00:00
Start here when contributing to ConfigKit. Read the task-specific owners below
before making changes. The [component overview ](internal/overview.md ) maps
implementation responsibilities; the [configuration contract ](config.md ) owns
public behavior.
2026-09-06 10:52:38 -05:00
2026-09-06 11:48:22 -05:00
## Initial orientation
2026-09-06 10:52:38 -05:00
2026-09-06 11:48:22 -05:00
1. Inspect the working tree and preserve unrelated changes.
2026-09-28 00:27:03 +00:00
2. Use the Policy Reading Guide below to select applicable policies.
3. Read the contract and internal documents applicable to the task.
2026-09-07 01:40:39 +00:00
4. Inspect the relevant implementation and behavioral tests before changing them.
2026-09-06 10:52:38 -05:00
2026-09-28 00:27:03 +00:00
## Policy Reading Guide
| Policy | Read before… |
| --- | --- |
| [Policy set provenance ](policy/meta.md ) | Adopting policies, checking upstream revisions, or updating the adopted policy set. |
| [Agents ](policy/agents.md ) | Recommending, planning, or implementing repository changes. |
| [Architecture ](policy/architecture.md ) | Planning or changing Go library code or its structure. |
| [Testing ](policy/testing.md ) | Selecting validation for code changes, or adding, changing, removing, or evaluating tests. |
| [Documentation ](policy/documentation.md ) | Writing, revising, or reorganizing documentation. |
| [OSS ](policy/oss.md ) | Adding or updating dependencies or incorporated third-party material, or changing licensing or attribution. |
| [Release ](policy/release.md ) | 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.
2026-09-06 11:48:22 -05:00
## Task-specific reading guide
2026-09-06 10:52:38 -05:00
2026-09-06 11:48:22 -05:00
| Task | Read |
| --- | --- |
2026-09-28 00:27:03 +00:00
| Repository orientation or component responsibility | [Component overview ](internal/overview.md ) |
2026-10-14 14:06:38 +00:00
| Input destinations | [Configuration contract ](config.md#input-destinations ), [ADR 0011 ](adr/0011-input-destinations.md ), and the destination tests below |
2026-10-15 16:23:39 +00:00
| Shared source-version checks | [Configuration contract ](config.md#shared-source-version-checks ), [ADR 0013 ](adr/0013-shared-source-version-checks.md ), and the version/source-version tests below |
2026-09-28 00:27:03 +00:00
| Documentation changes | The owning document |
| Licensing, dependencies, attribution, or release-document changes | [Project grant ](../COPYRIGHT ) and [attribution ](oss/attribution.md ); release changes also follow the release procedure |
2026-10-27 19:15:40 +00:00
| Architecture decisions or future work | [Future features ](roadmap/future.md ) and relevant ADRs listed below |
2026-09-28 00:27:03 +00:00
| Code and test changes | The owning contract and tests from the map below |
2026-09-06 22:26:14 +00:00
| Examples or copyable assets | The owning implemented contract and [consumer adoption guide ](consumers/README.md ) |
2026-09-28 00:27:03 +00:00
| Release preparation | [Release procedure ](release.md ) |
2026-09-06 10:52:38 -05:00
2026-09-06 11:48:22 -05:00
Accepted decisions:
2026-09-06 10:52:38 -05:00
2026-09-06 11:48:22 -05:00
- [Separate composition and overlay ](adr/0001-separate-composition-and-overlay.md )
2026-10-15 15:02:50 +00:00
- [Check source versions with one shared policy ](adr/0013-shared-source-version-checks.md )
2026-09-06 11:48:22 -05:00
- [Own YAML semantics behind a private parser boundary ](adr/0002-own-yaml-semantics.md )
- [Preserve presence and record application resolution ](adr/0003-preserve-presence-and-resolution-history.md )
2026-11-18 00:16:53 +00:00
- [Explicit configured secrets bootstrap ](adr/0023-explicit-configured-secrets-bootstrap.md )
2026-09-06 13:59:01 -05:00
- [Explicit overrides and safe explanation ](adr/0005-explicit-overrides-and-safe-explanation.md )
2026-09-12 15:56:11 +00:00
- [Keep the public facade root-owned ](adr/0006-public-facade.md )
2026-10-09 12:42:17 +00:00
- [Compare frozen effective configuration snapshots ](adr/0010-effective-configuration-diff.md )
2026-11-21 04:16:46 +00:00
- [Compare inspection views across application types ](adr/0024-compare-inspection-views-across-application-types.md )
2026-10-14 14:06:38 +00:00
- [Place inputs at literal application mapping paths ](adr/0011-input-destinations.md )
2026-10-19 21:23:47 +00:00
- [Share dependency-ready ordering ](adr/0015-shared-dependency-ready-ordering.md )
- [Separate import selection controls ](adr/0016-independent-import-controls.md )
2026-10-23 01:09:24 +00:00
- [Define identity and merge rules for each collection ](adr/0017-collection-sequence-policy.md )
- [Apply CLI overrides after inheritance and decoding ](adr/0018-cli-after-structural-resolution.md )
2026-10-24 16:24:57 +00:00
- [Keep main-file discovery explicit and composable ](adr/0019-explicit-configuration-discovery.md )
2026-11-02 00:45:36 +00:00
- [Scope configuration controls to document roots ](adr/0020-document-root-controls.md )
2026-11-03 01:01:25 +00:00
- [Match registered records during resolution inspection ](adr/0021-sequence-resolution-correspondence.md )
2026-11-09 20:47:44 +00:00
- [Bind companion contexts after main selection ](adr/0022-main-relative-context.md )
2026-09-06 13:59:01 -05:00
2026-11-21 12:36:10 +00:00
For cross-cutting changes, follow every applicable row. Use current contracts
and the component overview for ongoing work.
2026-09-07 01:42:57 +00:00
2026-09-07 01:52:38 +00:00
Release-candidate, publication, and verification work follows the operational
2026-10-08 16:46:28 +00:00
[release procedure ](release.md ). 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.
2026-09-06 10:52:38 -05:00
2026-09-06 11:48:22 -05:00
## Baseline validation
2026-09-06 10:52:38 -05:00
2026-10-08 16:46:28 +00:00
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:
2026-09-06 10:52:38 -05:00
2026-09-06 11:48:22 -05:00
```sh
2026-09-06 19:13:36 +00:00
go mod download
2026-09-06 11:48:22 -05:00
```
2026-09-06 10:52:38 -05:00
2026-09-07 01:40:39 +00:00
Run the everyday check with Bash 3.2 or newer and Git:
2026-09-06 19:13:36 +00:00
```sh
2026-09-07 01:40:39 +00:00
./scripts/check.sh
2026-09-06 19:13:36 +00:00
```
2026-09-06 10:52:38 -05:00
2026-09-07 01:40:39 +00:00
[The script ](../scripts/check.sh ) 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,
2026-11-03 01:32:05 +00:00
and the dependency/public boundary checks.
2026-09-07 01:40:39 +00:00
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
2026-11-03 01:32:05 +00:00
under the testing policy. Documentation-only work normally needs review of
affected links and whitespace; behavior-bearing examples and commands also
need execution. Automated Markdown link checking runs against the committed
candidate through ReleaseKit, not during ordinary Go tests or the everyday
checker. See the [release procedure ](release.md#4-publish-the-committed-candidate )
for the selected checks and optional diagnostic command. Use
`go test -race ./...` for ownership or concurrency changes.
2026-10-08 16:46:28 +00:00
The [release procedure ](release.md#4-publish-the-committed-candidate ) 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.
2026-09-07 01:40:39 +00:00
## 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 |
| --- | --- | --- |
2026-09-12 16:26:44 +00:00
| YAML syntax, diagnostics, parser limits | [Adapter tests ](../internal/yaml/parse_test.go ), [source translation ](../internal/engine/parse_test.go ) | `go test ./internal/yaml` and `go test ./internal/engine -run '^TestParseSource'` |
2026-10-25 13:49:44 +00:00
| File/reader access, imports, globs, containment | [Import internals ](internal/imports.md ), [source acquisition ](../internal/engine/source_test.go ), [FIFO ](../internal/engine/source_fifo_test.go ), [import traversal ](../internal/engine/imports_test.go ), [import evidence ](../internal/engine/import_evidence_test.go ), [relative destinations ](../internal/engine/destination_import_test.go ), [globs ](../internal/engine/glob_test.go ) | `go test ./internal/engine -run 'Source\|Import\|Glob\|Filesystem\|Nonregular\|RegularFile'` |
2026-11-01 17:53:39 +00:00
| Explicit main-file discovery and absent-input loading | [Candidate selection ](../internal/engine/discovery_test.go ), [load integration ](../internal/engine/discovery_load_test.go ), [public facade ](../facade_discovery_test.go ), and maintained [catalog ](../examples/consumers/sequence_catalog_test.go ) and [preset ](../examples/consumers/discovery_test.go ) examples | `go test ./internal/engine -run 'Discovery\|Search'` , `go test . -run 'Search'` , and `go test ./examples/consumers -run 'WorkingDirectoryPreset\|SequenceCatalog'` |
| Import defaults, empty-selection evidence, and dependency-ready ordering | [Defaults and facade evidence ](../facade_import_defaults_test.go ), [engine import evidence ](../internal/engine/import_evidence_test.go ), [scheduler ](../internal/engine/dependency_order_test.go ), [scheduling integrations ](../internal/engine/imports_test.go ) | `go test ./internal/engine -run 'Import\|ScheduleDependencies\|Inheritance'` , `go test . -run 'ImportDefaults\|FacadeImport'` , and `go test ./examples/consumers` |
2026-09-29 18:22:45 +00:00
| Native filesystem and mapping sources | [Native acquisition ](../internal/engine/native_filesystem_test.go ), [filesystem facade ](../facade_filesystem_test.go ), [mapping facade ](../facade_mapping_test.go ) | `go test ./internal/engine -run 'NativeFilesystem'` and `go test . -run 'TestFacade'` |
2026-09-23 18:27:29 +00:00
| Composition, selected overlays, CLI precedence | [Composition ](../internal/engine/compose_test.go ), [overlay ](../internal/engine/overlay_test.go ), [selected overlays ](../internal/engine/selected_overlay_test.go ), [overrides ](../internal/engine/override_test.go ) | `go test ./internal/engine -run 'Compose\|Overlay\|Override'` |
2026-10-23 21:57:35 +00:00
| Sequence identity, declarations, and operations | [Identity ](../internal/engine/sequence_identity_test.go ), [registrations ](../internal/engine/sequence_registration_test.go ), [declarations ](../internal/engine/sequence_declaration_test.go ), [combination ](../internal/engine/sequence_combine_test.go ), [final facade validation ](../facade_final_sequence_identity_test.go ), and [consumer catalog ](../examples/consumers/sequence_catalog_test.go ) | `go test ./internal/engine -run 'Sequence\|Collection'` , `go test . -run 'SequenceIdentity\|SequenceRegistration'` , and `go test ./examples/consumers` |
2026-10-25 13:49:44 +00:00
| Sibling inheritance, provenance, history, sensitivity | [Implementation flow ](internal/overview.md#implementation-flow ), [expansion ](../internal/engine/inheritance_test.go ), [destination scopes ](../internal/engine/inheritance_walk_test.go ), [origins ](../internal/engine/inheritance_origin_test.go ), [history ](../internal/engine/inheritance_history_test.go ), [secrets ](../internal/engine/inheritance_secret_test.go ), [public loading ](../facade_inheritance_test.go ) | `go test ./internal/engine -run 'Inheritance\|Inherited'` and `go test . -run '^TestFacadeInheritance\|^TestFacadeInheritedSecrets'` |
2026-09-29 18:22:45 +00:00
| Layered loading and source equivalence | [Grouped lifecycle ](../internal/engine/load_request_test.go ), [layered facade ](../facade_layered_test.go ), [equivalence ](../facade_equivalence_test.go ) | `go test ./internal/engine -run '^TestGrouped'` , `go test . -run '^TestFacadeLayered'` , and `go test . -run '^TestEquivalentSourceForms'` |
2026-11-01 17:53:39 +00:00
| Input and relative-import destinations, mounted sources, and source ownership | [Destination engine tests ](../internal/engine/destination_test.go ), [tier tests ](../internal/engine/destination_tiers_test.go ), [import traversal and version tests ](../internal/engine/destination_import_test.go ), [accounting tests ](../internal/engine/destination_accounting_test.go ), [lifecycle inspection tests ](../internal/engine/destination_import_lifecycle_test.go ), [public source/error tests ](../facade_destination_test.go ), [resource contexts ](../facade_resource_context_test.go ), and [consumer examples ](../examples/consumers/destinations_test.go ) | `go test ./internal/engine -run 'Destination\|Import\|Glob\|Mounted'` , `go test . -run 'Destination\|Import\|SourceContext\|FacadeMounted'` , and `go test ./examples/consumers` |
2026-10-15 16:23:39 +00:00
| Shared source-version modes and evidence | [Engine source-version tests ](../internal/engine/source_version_test.go ), [public facade tests ](../facade_source_version_mode_test.go ), and [consumer example tests ](../examples/consumers/layered_test.go ) | `go test ./internal/engine -run 'SourceVersion'` , `go test . -run 'SourceVersion'` , and `go test ./examples/consumers` |
2026-10-25 14:58:56 +00:00
| Schema, defaults, projection, cloning | [Implementation flow ](internal/overview.md#implementation-flow ), [schema ](../internal/engine/schema_test.go ), [decoding ](../internal/engine/decode_test.go ), [projection and typed cloning ](../internal/engine/projection_test.go ) | `go test ./internal/engine -run 'Schema\|Decode\|Projection\|Clone\|Inline\|CompareDocument'` |
2026-11-21 04:16:46 +00:00
| Current values and focused inspection | [Value tests ](../facade_result_value_test.go ), [view tests ](../facade_inspection_view_test.go ), [comparison tests ](../facade_inspection_diff_test.go ), and [history integration ](../facade_inspection_history_test.go ) | `go test . -run 'TestResultValue\|TestInspectionView'` and `go test ./internal/engine -run 'TestResultValue\|Diff\|History'` |
2026-09-12 16:26:44 +00:00
| Lifecycle, resolution, validation, callback ownership | [Loading ](../internal/engine/load_test.go ), [resolution ](../internal/engine/resolution_test.go ), [validation ](../internal/engine/validation_test.go ), [ownership ](../internal/engine/callback_ownership_test.go ), [independence ](../internal/engine/independence_test.go ) | `go test ./internal/engine -run 'Load\|Resolution\|Validation\|Validator\|Hook\|Callback\|Parallel'` |
2026-11-03 01:01:25 +00:00
| Resolution sequence matching and inspection | [Correspondence ](../internal/engine/resolution_correspondence_test.go ), [auditing and history ](../internal/engine/resolution_compare_test.go ), [public integration ](../facade_resolution_sequences_test.go ) | `go test ./internal/engine -run 'Resolution\|History\|Explain\|Sensitivity'` and `go test . -run 'Resolution\|SequenceIdentity\|Diff'` |
2026-09-12 16:26:44 +00:00
| Paths, metadata, provenance | [Paths ](../internal/engine/path_test.go ), [metadata ](../internal/engine/metadata_test.go ), [provenance ](../internal/engine/provenance_test.go ) | `go test ./internal/engine -run 'Path\|Metadata\|Provenance\|Queries'` |
2026-09-29 18:22:45 +00:00
| Passive resource contexts | [Engine contexts ](../internal/engine/resource_context_test.go ), [public contexts ](../facade_resource_context_test.go ) | `go test ./internal/engine -run 'Resource'` and `go test . -run 'SourceContext'` |
2026-11-18 01:10:24 +00:00
| Secrets, bootstrap, redaction, explanation | [References ](../internal/engine/secret_reference_test.go ), [directory bootstrap ](../internal/engine/secrets_test.go ), [configured preparation ](../internal/engine/secrets_from_config_test.go ), [public handoff ](../facade_secrets_handoff_test.go ), [consumer example ](../examples/consumers/secrets_test.go ), [rendering ](../internal/engine/render_test.go ), [explanation ](../internal/engine/explain_test.go ) | `go test ./internal/engine -run 'Secret\|Bootstrap\|Effective\|Explain\|Explanation\|History\|Sensitivity'` , `go test . -run 'Secrets\|Bootstrap'` , and `go test ./examples/consumers -run 'ConfiguredSecrets'` |
2026-11-01 17:53:39 +00:00
| Effective configuration diff | [Engine comparison and masking tests ](../internal/engine/diff_test.go ), [engine operation tests ](../internal/engine/diff_operation_test.go ), [root facade tests ](../facade_diff_test.go ), and [consumer examples ](../examples/consumers/diff_test.go ) | `go test ./internal/engine -run 'Diff\|Explain\|History\|Secret\|Independent'` , `go test . -run 'Diff\|FacadeInspection\|PublicFacadeBoundary\|DependencyImportBoundary'` , `go test ./examples/consumers` , and `go test . -run '^ExampleDiff$'` |
2026-10-14 17:45:31 +00:00
| Consumer examples and migration fixtures | [Consumer tests ](../examples/consumers/consumers_test.go ), [native, layered, and ordinary relative-import examples ](../examples/consumers/layered_test.go ), [mounted collection examples ](../examples/consumers/destinations_test.go ), [API examples ](../example_test.go ) | `go test ./examples/consumers` and `go test . -run '^Example'` |
2026-09-29 18:22:45 +00:00
| Assembly and layered scaling evidence | [Assembly benchmarks ](../internal/engine/assembly_bench_test.go ), [layered benchmarks ](../internal/engine/underlay_bench_test.go ) | `go test ./internal/engine -run '^$' -bench '^BenchmarkUnderlay' -benchmem` ; repeat with `^BenchmarkCompose` and `^BenchmarkOverlay` |
2026-10-23 22:03:16 +00:00
| Identified-sequence scaling evidence | [Mixed-upsert benchmark ](../internal/engine/sequence_combine_bench_test.go ) | `go test ./internal/engine -run '^$' -bench '^BenchmarkSequenceMixedUpsert$' -benchmem` |
2026-09-29 23:13:50 +00:00
| Inheritance scaling evidence | [Expansion benchmarks ](../internal/engine/inheritance_bench_test.go ) | `go test ./internal/engine -run '^$' -bench '^BenchmarkInheritance' -benchmem` |
2026-11-03 01:32:05 +00:00
| Dependency and public API isolation | [Import boundary ](../import_boundary_test.go ), [public boundary ](../public_boundary_test.go ) | `go test . -run 'TestDependencyImportBoundary\|TestPublicFacadeBoundary'` |
2026-10-08 16:46:28 +00:00
| Development check behavior | [Development checker test ](../development_check_test.go ) | `go test . -run '^TestDevelopmentCheckHandlesFilenamesAndStopsOnFailure$'` |
2026-09-12 16:26:44 +00:00
## Fuzz validation
Run the bounded fuzz targets independently from the repository root. These exact
commands keep each campaign short and constrain concurrent workers:
```sh
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
2026-09-06 22:35:01 +00:00
```