86 lines
4.1 KiB
Markdown
86 lines
4.1 KiB
Markdown
# Development
|
|
|
|
This is the contributor entry point for ConfigKit. Read the task-specific owners
|
|
below before making changes. The repository is in early implementation: its public
|
|
loader currently covers strict selected sources, explicit path/glob import graphs,
|
|
composition, selected profile overlays, typed defaults, schema-version checks,
|
|
explicit CLI overrides, recorded application resolution, semantic validation,
|
|
layered metadata, secret
|
|
classification, typed environment references, explicit secrets bootstrap, and
|
|
redacted effective rendering and historical value explanation. The
|
|
[component overview](internal/overview.md) owns the implementation inventory.
|
|
|
|
## 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 relevant implementation and tests where they exist 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), [initial target design](roadmap/initial.md), and relevant ADRs listed below |
|
|
| Code and test changes | [Architecture policy](policy/architecture.md), [testing policy](policy/testing.md), and owning contracts/tests as they are introduced |
|
|
| Examples or copyable assets | The owning implemented contract and [consumer adoption guide](consumers/README.md) |
|
|
| Release preparation | [Release policy](policy/release.md) and [release-readiness gaps](roadmap/release-readiness.md); the operational runbook will be added before release |
|
|
|
|
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. The
|
|
[implementation plan](roadmap/implementation.md) owns the ordered stages and their
|
|
acceptance checks and recorded implementation evidence.
|
|
|
|
## 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 library baseline from the repository root:
|
|
|
|
```sh
|
|
go test ./...
|
|
go vet ./...
|
|
go build ./...
|
|
git diff --check
|
|
```
|
|
|
|
The default tests must remain deterministic and runnable without network access or
|
|
credentials after dependency acquisition. Also inspect new untracked files, verify
|
|
changed local links and heading fragments, and review paths, examples, ownership,
|
|
and current-versus-planned claims. The commands above do not check links or
|
|
untracked content. Do not use an application binary build as the library baseline.
|
|
Add executable-example and other checks when those artifacts are introduced; do
|
|
not document nonexistent tools as operational.
|
|
|
|
Once code exists, use focused checks while iterating and validation proportionate
|
|
to the change under the testing policy. Documentation-only work does not require
|
|
Go checks unless it changes behavior-bearing examples or commands they validate.
|
|
Release validation is a separate, stricter gate governed by release policy.
|
|
|
|
## 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
|
|
```
|