167 lines
17 KiB
Markdown
167 lines
17 KiB
Markdown
# Development
|
|
|
|
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.
|
|
|
|
## Initial orientation
|
|
|
|
1. Inspect the working tree and preserve unrelated changes.
|
|
2. Use the Policy Reading Guide below to select applicable policies.
|
|
3. Read the contract and internal documents applicable to the task.
|
|
4. Inspect the relevant implementation and behavioral tests before changing them.
|
|
|
|
## 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.
|
|
|
|
## Task-specific reading guide
|
|
|
|
| Task | Read |
|
|
| --- | --- |
|
|
| Repository orientation or component responsibility | [Component overview](internal/overview.md) |
|
|
| Input destinations | [Configuration contract](config.md#input-destinations), [ADR 0011](adr/0011-input-destinations.md), and the destination tests below |
|
|
| 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 |
|
|
| 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 |
|
|
| Architecture decisions or future work | [Future features](roadmap/future.md) 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](consumers/README.md) |
|
|
| Release preparation | [Release procedure](release.md) |
|
|
|
|
Accepted decisions:
|
|
|
|
- [Separate composition and overlay](adr/0001-separate-composition-and-overlay.md)
|
|
- [Check source versions with one shared policy](adr/0013-shared-source-version-checks.md)
|
|
- [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)
|
|
- [Explicit configured secrets bootstrap](adr/0023-explicit-configured-secrets-bootstrap.md)
|
|
- [Explicit overrides and safe explanation](adr/0005-explicit-overrides-and-safe-explanation.md)
|
|
- [Keep the public facade root-owned](adr/0006-public-facade.md)
|
|
- [Compare frozen effective configuration snapshots](adr/0010-effective-configuration-diff.md)
|
|
- [Compare inspection views across application types](adr/0024-compare-inspection-views-across-application-types.md)
|
|
- [Place inputs at literal application mapping paths](adr/0011-input-destinations.md)
|
|
- [Share dependency-ready ordering](adr/0015-shared-dependency-ready-ordering.md)
|
|
- [Separate import selection controls](adr/0016-independent-import-controls.md)
|
|
- [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)
|
|
- [Keep main-file discovery explicit and composable](adr/0019-explicit-configuration-discovery.md)
|
|
- [Scope configuration controls to document roots](adr/0020-document-root-controls.md)
|
|
- [Match registered records during resolution inspection](adr/0021-sequence-resolution-correspondence.md)
|
|
- [Bind companion contexts after main selection](adr/0022-main-relative-context.md)
|
|
|
|
For cross-cutting changes, follow every applicable row. Use current contracts
|
|
and the component overview for ongoing work.
|
|
|
|
Release-candidate, publication, and verification work follows the operational
|
|
[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.
|
|
|
|
## Baseline validation
|
|
|
|
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:
|
|
|
|
```sh
|
|
go mod download
|
|
```
|
|
|
|
Run the everyday check with Bash 3.2 or newer and Git:
|
|
|
|
```sh
|
|
./scripts/check.sh
|
|
```
|
|
|
|
[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,
|
|
and the dependency/public boundary checks.
|
|
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 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.
|
|
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.
|
|
|
|
## 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](../internal/yaml/parse_test.go), [source translation](../internal/engine/parse_test.go) | `go test ./internal/yaml` and `go test ./internal/engine -run '^TestParseSource'` |
|
|
| 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'` |
|
|
| 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` |
|
|
| 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'` |
|
|
| 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'` |
|
|
| 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` |
|
|
| 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'` |
|
|
| 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'` |
|
|
| 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` |
|
|
| 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` |
|
|
| 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'` |
|
|
| 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'` |
|
|
| 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'` |
|
|
| 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'` |
|
|
| 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'` |
|
|
| 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'` |
|
|
| 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'` |
|
|
| 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$'` |
|
|
| 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'` |
|
|
| 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` |
|
|
| Identified-sequence scaling evidence | [Mixed-upsert benchmark](../internal/engine/sequence_combine_bench_test.go) | `go test ./internal/engine -run '^$' -bench '^BenchmarkSequenceMixedUpsert$' -benchmem` |
|
|
| Inheritance scaling evidence | [Expansion benchmarks](../internal/engine/inheritance_bench_test.go) | `go test ./internal/engine -run '^$' -bench '^BenchmarkInheritance' -benchmem` |
|
|
| Dependency and public API isolation | [Import boundary](../import_boundary_test.go), [public boundary](../public_boundary_test.go) | `go test . -run 'TestDependencyImportBoundary\|TestPublicFacadeBoundary'` |
|
|
| Development check behavior | [Development checker test](../development_check_test.go) | `go test . -run '^TestDevelopmentCheckHandlesFilenamesAndStopsOnFailure$'` |
|
|
|
|
## 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
|
|
```
|