32 lines
1.7 KiB
Markdown
32 lines
1.7 KiB
Markdown
# Documentation Policy
|
|
|
|
## Purpose
|
|
|
|
This policy defines how architectural knowledge is captured and maintained.
|
|
|
|
## Mandatory Rules
|
|
|
|
- Record every architecture decision in the Bible before or together with implementation.
|
|
- Use English for all architecture documentation.
|
|
- External integration handoff documents may use the consumer language when needed, but they must be explicitly marked as external-facing.
|
|
- Keep only current architecture in active sections.
|
|
- When a solution is replaced, update or remove obsolete guidance in the same change.
|
|
- Keep shared rules in `bible/` and project-specific architecture in `bible-local/`; other top-level docs should only reference them.
|
|
|
|
## Change Workflow
|
|
|
|
1. Update the relevant file(s) in `bible-local/architecture/` or `bible-local/docs/`.
|
|
2. If behavior changed or documentation policy changed, add or update a decision note in `bible-local/decisions/`.
|
|
3. Remove duplicated or outdated statements from non-Bible docs.
|
|
4. Validate consistency against code paths in `internal/api`, `internal/ingest`, and `internal/repository`.
|
|
|
|
## Hardware Ingest Contract
|
|
|
|
`bible-local/docs/hardware-ingest-contract.md` is a distributable integration document for external teams.
|
|
|
|
**Mandatory:** any change to the hardware JSON import contract (`HardwareIngestRequest`, `HardwareSnapshot`, or any nested struct in `internal/ingest/parser_hardware.go`) must be reflected in `hardware-ingest-contract.md` in the same commit:
|
|
|
|
- Bump the `version` field in the YAML front matter (patch for additive/optional fields, minor for new sections, major for breaking changes).
|
|
- Update the `updated` date.
|
|
- Add a row to the Changelog table describing what changed.
|