42 lines
2.5 KiB
Markdown
42 lines
2.5 KiB
Markdown
# Architecture Decision Records (ADRs)
|
||
|
||
Architecture Decision Records document long-lived choices that shape StellaOps architecture, security posture, and operator experience. They complement RFCs by capturing the final call and the context that led to it.
|
||
|
||
## When to file an ADR
|
||
- Decisions that affect cross-module contracts, persistence models, or external interfaces.
|
||
- Security or compliance controls with on-going operational ownership.
|
||
- Rollout strategies that require coordination across guilds or sprints.
|
||
- Reversals or deprecations of previously accepted ADRs.
|
||
|
||
Small, module-local refactors that do not modify public behaviour can live in commit messages instead.
|
||
|
||
## Workflow at a glance
|
||
1. Copy `docs/adr/0000-template.md` to `docs/adr/NNNN-short-slug.md` with a zero-padded sequence (see **Numbering**).
|
||
2. Fill in context, decision, consequences, and alternatives. Include links to RFCs, issues, benchmarks, or experiments.
|
||
3. Request async review from the impacted guilds. Capture sign-offs in the **Deciders** field.
|
||
4. Merge the ADR with the code/config changes (or in a preparatory PR).
|
||
5. Announce the accepted ADR in the Docs Guild channel or sprint notes so downstream teams can consume it.
|
||
|
||
## Numbering and status
|
||
- Use zero-padded integers (e.g., `0001`, `0002`) in file names and the document header. Increment from the highest existing number.
|
||
- Valid statuses: `Proposed`, `Accepted`, `Rejected`, `Deprecated`, `Superseded`. Update the status when follow-up work lands.
|
||
- When an ADR supersedes another, link them in both documents’ **References** sections.
|
||
|
||
## Review expectations
|
||
- Highlight edge-case handling, trade-offs, and determinism requirements.
|
||
- Include operational checklists for any new runtime path (quota updates, schema migrations, credential rotation, etc.).
|
||
- Attach diagrams under `docs/adr/assets/` when visuals improve comprehension.
|
||
- Add TODO tasks for follow-up work in the relevant module’s `TASKS.md` and link them from the ADR.
|
||
|
||
## Verification checklist
|
||
- [ ] `Status`, `Date`, `Authors`, and `Deciders` populated.
|
||
- [ ] Links to code/config PRs or experiments recorded under **References**.
|
||
- [ ] Consequences call out migration or rollback steps.
|
||
- [ ] Announcement posted to Docs Guild updates (or sprint log).
|
||
|
||
## Related resources
|
||
- [Docs Guild Task Board](../TASKS.md)
|
||
- [High-Level Architecture Overview](../07_HIGH_LEVEL_ARCHITECTURE.md)
|
||
- [Coding Standards](../18_CODING_STANDARDS.md)
|
||
- [Release Engineering Playbook](../13_RELEASE_ENGINEERING_PLAYBOOK.md)
|