61 lines
3.2 KiB
Markdown
61 lines
3.2 KiB
Markdown
# Development
|
|
|
|
This is the contributor entry point for ConfigKit. Read the task-specific owners
|
|
below before making changes. The repository is in pre-implementation: it has no
|
|
Go module, packages, tests, or executable examples yet. 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 related maintained examples, once available |
|
|
| 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; all remain pending until implementation evidence is recorded.
|
|
|
|
## Baseline validation
|
|
|
|
For the current documentation-only repository:
|
|
|
|
```sh
|
|
git diff --check
|
|
```
|
|
|
|
Also inspect new untracked documents, verify changed local links and heading
|
|
fragments, and review paths, examples, ownership, and current-versus-planned
|
|
claims. The command above does not check links or untracked content.
|
|
|
|
Go validation is not runnable until a module and packages exist. The scaffolding
|
|
change must establish and verify library test, vet, and build commands here,
|
|
including their prerequisites. 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.
|