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.
2.7 KiB
2.7 KiB
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
- Copy
docs/adr/0000-template.mdtodocs/adr/NNNN-short-slug.mdwith a zero-padded sequence (see Numbering). - Fill in context, decision, consequences, and alternatives. Include links to RFCs, issues, benchmarks, or experiments.
- Request async review from the impacted guilds. Capture sign-offs in the Deciders field.
- Merge the ADR with the code/config changes (or in a preparatory PR).
- 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.mdand link them from the ADR.
Verification checklist
Status,Date,Authors, andDeciderspopulated.- 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 | PostgreSQL for Control-Plane Storage | Accepted | 2025-12-04 |