75f6942769
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Policy Lint & Smoke / policy-lint (push) Has been cancelled
Concelier Attestation Tests / attestation-tests (push) Has been cancelled
AOC Guard CI / aoc-guard (push) Has been cancelled
AOC Guard CI / aoc-verify (push) Has been cancelled
- Implemented MigrationCategoryTests to validate migration categorization for startup, release, seed, and data migrations. - Added tests for edge cases, including null, empty, and whitespace migration names. - Created StartupMigrationHostTests to verify the behavior of the migration host with real PostgreSQL instances using Testcontainers. - Included tests for migration execution, schema creation, and handling of pending release migrations. - Added SQL migration files for testing: creating a test table, adding a column, a release migration, and seeding data.
49 lines
2.7 KiB
Markdown
49 lines
2.7 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).
|
||
|
||
## ADR Index
|
||
|
||
| ADR | Title | Status | Date |
|
||
|-----|-------|--------|------|
|
||
| [0001](./0001-postgresql-for-control-plane.md) | PostgreSQL for Control-Plane Storage | Accepted | 2025-12-04 |
|
||
|
||
## Related resources
|
||
- [Docs Guild Task Board](../TASKS.md)
|
||
- [High-Level Architecture Overview](../07_HIGH_LEVEL_ARCHITECTURE.md)
|
||
- [Database Documentation](../db/README.md)
|
||
- [Coding Standards](../18_CODING_STANDARDS.md)
|
||
- [Release Engineering Playbook](../13_RELEASE_ENGINEERING_PLAYBOOK.md)
|