Public Access
131 lines
4.0 KiB
Markdown
131 lines
4.0 KiB
Markdown
# Spec-Driven Development
|
|
|
|
## Overview
|
|
|
|
Every change starts with a spec. No spec, no code. No code, no PR.
|
|
|
|
The spec is a markdown file at `docs/specs/<TASK-ID>.md` in the repo.
|
|
It contains structured requirements (REQ-IDs) and acceptance criteria
|
|
(AC checklist) that CI validates before merge.
|
|
|
|
## Workflow
|
|
|
|
1. **Create Vikunja task** — `make create-task -- --title "Title" --description "..."`
|
|
2. **Write spec** — Create `docs/specs/<TASK-ID>.md` (see template below)
|
|
3. **Create branch** — `git checkout -b <PREFIX>-N-short-description`
|
|
4. **Implement** — Write code with `# Implements: REQ-N` comments
|
|
5. **Check ACs** — Tick all acceptance criteria checkboxes in the spec
|
|
6. **Push and create PR** — `make push-with-pr`
|
|
7. **CI validates** — Spec validation, PR size check, fast molecule, lint, tests
|
|
8. **Auto-merge** — Add `ready-to-merge` label after review
|
|
9. **Auto-deploy** — Post-merge deploys to staging (if nightly gate is green)
|
|
|
|
## Spec Template
|
|
|
|
```markdown
|
|
# <TASK-ID>: <Title>
|
|
|
|
## Problem
|
|
<What is broken or missing? Why does this change exist?>
|
|
|
|
## Approach
|
|
<How will you solve it? What are the key design decisions?>
|
|
|
|
REQ-1: <First requirement description>
|
|
REQ-2: <Second requirement description>
|
|
REQ-3: <Third requirement description>
|
|
|
|
## Test Plan
|
|
- <How will you verify each REQ is implemented correctly?>
|
|
- <Include unit tests, molecule scenarios, integration tests>
|
|
|
|
## Deploy Plan
|
|
- <How will this change be deployed?>
|
|
- <What order do components need to deploy in?>
|
|
- <Are there migrations or one-time operations?>
|
|
|
|
## Rollback Plan
|
|
- <How do you revert if something goes wrong?>
|
|
- <What data/state changes are irreversible?>
|
|
|
|
## Acceptance Criteria
|
|
- [ ] REQ-1: <criterion that proves REQ-1 is done>
|
|
- [ ] REQ-2: <criterion that proves REQ-2 is done>
|
|
- [ ] REQ-3: <criterion that proves REQ-3 is done>
|
|
```
|
|
|
|
## CI Validation
|
|
|
|
The `devx.ci.validate_spec` module checks:
|
|
|
|
1. **Spec file exists** at `docs/specs/<TASK-ID>.md` (TASK-ID from branch name)
|
|
2. **Required sections present**: Problem, Approach, Test Plan, Deploy Plan, Rollback Plan, Acceptance Criteria
|
|
3. **At least one REQ-ID** line (format: `REQ-N: <description>`)
|
|
4. **All AC checkboxes checked** (`- [x]`, not `- [ ]`)
|
|
|
|
If any check fails, CI blocks the PR before expensive jobs run.
|
|
|
|
## PR Size Limits
|
|
|
|
CI enforces max 500 lines / 10 files changed (excluding CHANGELOG.md,
|
|
README.md, badges, lock files). Oversized PRs are rejected. Split your
|
|
work into smaller PRs.
|
|
|
|
## Code-to-Spec Linking
|
|
|
|
Each function, task, or template that implements a requirement should
|
|
have a comment:
|
|
|
|
```python
|
|
# Implements: REQ-1
|
|
def install_sso_bridge():
|
|
...
|
|
```
|
|
|
|
```yaml
|
|
# Implements: REQ-2
|
|
- name: Clone infra repo
|
|
git:
|
|
...
|
|
```
|
|
|
|
## Fast Molecule (Pre-merge)
|
|
|
|
CI runs molecule only for **changed roles** (detected via git diff),
|
|
with converge + verify only, single platform. This gives quick feedback
|
|
(~5-10 min) without the full molecule suite.
|
|
|
|
## Full Molecule (Nightly)
|
|
|
|
The complete molecule suite (all scenarios, all platforms) runs nightly
|
|
at 02:00 CET on master. If it fails:
|
|
- A Gitea issue is created with the `feedback` label
|
|
- The `NIGHTLY_STATUS` repo variable is set to `failed:<run_id>`
|
|
- All staging deploys are blocked until nightly passes again
|
|
|
|
## Auto-Deploy on Merge
|
|
|
|
Every merged PR auto-deploys to staging (if nightly gate is green).
|
|
No manual trigger needed. The deploy runs the full pipeline:
|
|
provision → deploy-observability → deploy-customer → configure-oidc.
|
|
|
|
For grm/sso-bridge: post-merge publishes the package, then auto-creates
|
|
an infra PR to bump the pinned version. That infra PR auto-deploys when
|
|
merged.
|
|
|
|
## Key Commands
|
|
|
|
```bash
|
|
# Validate spec locally (before pushing)
|
|
python -m devx.ci.validate_spec --branch <PREFIX>-N-description
|
|
|
|
# Check PR size locally
|
|
python -m devx.ci.check_pr_size --base origin/master --head HEAD
|
|
|
|
# See which roles need fast molecule
|
|
python -m devx.ci.fast_molecule --base origin/master --head HEAD
|
|
|
|
# Check nightly gate status
|
|
python -m devx.ci.nightly_gate --repo oblachno/infra --action check
|
|
```
|