Add an everyday check command and contributor test map
This commit is contained in:
@@ -1,21 +1,16 @@
|
||||
# Development
|
||||
|
||||
This is the contributor entry point for ConfigKit. Read the task-specific owners
|
||||
below before making changes. 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.
|
||||
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 relevant implementation and tests where they exist before changing them.
|
||||
4. Inspect the relevant implementation and behavioral tests before changing them.
|
||||
|
||||
## Task-specific reading guide
|
||||
|
||||
@@ -24,7 +19,7 @@ redacted effective rendering and historical value explanation. The
|
||||
| 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 record](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 |
|
||||
| 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), [release procedure](release.md), and [release-readiness evidence](roadmap/release-readiness.md) |
|
||||
|
||||
@@ -33,7 +28,6 @@ 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)
|
||||
|
||||
@@ -51,27 +45,51 @@ environment:
|
||||
go mod download
|
||||
```
|
||||
|
||||
Run the library baseline from the repository root:
|
||||
Run the everyday check with Bash 3.2 or newer and Git:
|
||||
|
||||
```sh
|
||||
go test ./...
|
||||
go vet ./...
|
||||
go build ./...
|
||||
git diff --check
|
||||
./scripts/check.sh
|
||||
```
|
||||
|
||||
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.
|
||||
[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>`.
|
||||
|
||||
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.
|
||||
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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user