120 lines
7.3 KiB
Markdown
120 lines
7.3 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. Read the architecture policy for code or design work.
|
|
3. Read the policy, contract, and internal documents applicable to the task.
|
|
4. Inspect the relevant implementation and behavioral tests before changing them.
|
|
|
|
## Task-specific reading guide
|
|
|
|
| Task | Read |
|
|
| --- | --- |
|
|
| Repository orientation or component responsibility | [Architecture policy](policy/architecture.md) and [component overview](internal/overview.md) |
|
|
| Documentation changes | [Documentation policy](policy/documentation.md) and the owning document |
|
|
| Architecture decisions or future work | [Documentation policy](policy/documentation.md), [deferred scope](roadmap/deferred.md), and relevant ADRs listed below |
|
|
| Code and test changes | [Architecture policy](policy/architecture.md), [testing policy](policy/testing.md), and 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 policy](policy/release.md) and [release procedure](release.md) |
|
|
|
|
Accepted decisions:
|
|
|
|
- [Separate composition and overlay](adr/0001-separate-composition-and-overlay.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)
|
|
- [Secret references and explicit bootstrap](adr/0004-secret-references-and-explicit-bootstrap.md)
|
|
- [Explicit overrides and safe explanation](adr/0005-explicit-overrides-and-safe-explanation.md)
|
|
|
|
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:
|
|
|
|
```sh
|
|
git show cb5b435:docs/roadmap/remediation.md
|
|
```
|
|
|
|
Release-candidate, publication, and verification work follows the operational
|
|
[release procedure](release.md).
|
|
|
|
The completed string-and-integer schema-version implementation and remediation
|
|
records are preserved in Git history at `244104f`. The
|
|
[configuration contract](config.md#application-schema-versions) owns current behavior.
|
|
|
|
The completed [source-origins during resolution record](roadmap/source-origins-during-resolution.md)
|
|
links to the current contract and evidence. Its staged implementation handoffs remain
|
|
in [implementation.md](roadmap/implementation.md) until release preparation retires
|
|
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:
|
|
|
|
```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,
|
|
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](release.md#4-validate-the-source-candidate) 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](../internal/yaml/parse_test.go), [source translation](../parse_test.go) | `go test ./internal/yaml` and `go test . -run '^TestParseSource'` |
|
|
| File/reader access, imports, globs, containment | [Sources](../source_test.go), [FIFO](../source_fifo_test.go), [imports](../imports_test.go), [globs](../glob_test.go) | `go test . -run 'Source\|Import\|Glob\|Filesystem\|Nonregular\|RegularFile'` |
|
|
| Composition, profiles, CLI precedence | [Composition](../compose_test.go), [overlay](../overlay_test.go), [profiles](../profile_test.go), [overrides](../override_test.go) | `go test . -run 'Compose\|Overlay\|Profile\|Override'` |
|
|
| Schema, defaults, projection, cloning | [Schema](../schema_test.go), [decoding](../decode_test.go), [projection](../projection_test.go) | `go test . -run 'Schema\|Decode\|Projection\|Clone\|Inline\|CompareDocument'` |
|
|
| Lifecycle, resolution, validation, callback ownership | [Loading](../load_test.go), [resolution](../resolution_test.go), [validation](../validation_test.go), [ownership](../callback_ownership_test.go), [independence](../independence_test.go) | `go test . -run 'Load\|Resolution\|Validation\|Validator\|Hook\|Callback\|Parallel'` |
|
|
| Paths, metadata, provenance | [Paths](../path_test.go), [metadata](../metadata_test.go), [provenance](../provenance_test.go) | `go test . -run 'Path\|Metadata\|Provenance\|Queries'` |
|
|
| Secrets, bootstrap, redaction, explanation | [References](../secret_reference_test.go), [bootstrap](../secrets_test.go), [rendering](../render_test.go), [explanation](../explain_test.go) | `go test . -run 'Secret\|Bootstrap\|Effective\|Explain\|Explanation\|History\|Sensitivity'` |
|
|
| Consumer examples and migration fixtures | [Consumer tests](../examples/consumers/consumers_test.go), [API examples](../example_test.go) | `go test ./examples/consumers` and `go test . -run '^Example'` |
|
|
| Documentation links and dependency isolation | [Link checks](../documentation_test.go), [import boundary](../import_boundary_test.go) | `go test . -run '^(TestLocalDocumentationLinks\|TestDependencyImportBoundary)$'` |
|
|
| 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:
|
|
|
|
```sh
|
|
go test . -run='^$' -fuzz='^FuzzParsePath$' -fuzztime=30s -parallel=2
|
|
go test ./internal/yaml -run='^$' -fuzz='^FuzzParseDocument$' -fuzztime=30s -parallel=2
|
|
go test . -run='^$' -fuzz='^FuzzCompositionAndOverlay$' -fuzztime=30s -parallel=2
|
|
```
|