doc updates
This commit is contained in:
1 parent
7e1bd4a9a4
commit
a511ff532e
26 files changed
+573
-770
No files matched your search
+20
-49
@@ -1,54 +1,25 @@
|
||||
# Workboard
|
||||
# Planning the next phase
|
||||
|
||||
Markdown workboard for building skyg-linux-tracker (CLI: `slinuxm`). The design lives in [`../plan.md`](../plan.md). This folder tracks the work.
|
||||
`plan/` is only for planning the next big piece of work, before it starts. It is empty of plans while the current board is clean.
|
||||
|
||||
| File | Purpose |
|
||||
Where other things live:
|
||||
|
||||
| What | Where |
|
||||
|---|---|
|
||||
| [`BOARD.md`](BOARD.md) | Kanban view. One row per workstream card, moved between columns. |
|
||||
| [`../TODO.md`](../TODO.md) | Master checklist. The only place task checkboxes are ticked. |
|
||||
| [`workstreams/`](workstreams/) | One card per workstream: goal, owned files, dependencies, design notes, done criteria, log. |
|
||||
| [`review.md`](review.md) | Design review of `plan.md`. Corrections and gaps, each mapped to a task. |
|
||||
| [`decisions.md`](decisions.md) | Decision log. Open questions and proposed defaults. |
|
||||
| Work tracking and checkboxes | [`../TODO.md`](../TODO.md) (tick boxes only there) |
|
||||
| Current design and decisions | [`../ARCHITECTURE.md`](../ARCHITECTURE.md) |
|
||||
| Long-form docs | [`../docs/`](../docs/README.md) |
|
||||
| Records of finished workstreams | [`../docs/workstreams/`](../docs/workstreams/) |
|
||||
|
||||
## Cards
|
||||
## Proposing a phase plan
|
||||
|
||||
| Card | Phase | Depends on | Owned files |
|
||||
|---|---|---|---|
|
||||
| [P0 Foundation](workstreams/P0-foundation.md) | 0 | — | `Cargo.toml`, `devenv.nix`, `config.example.toml`, `src/main.rs`, `src/config.rs`, `src/error.rs`, `src/state.rs`, `src/sources/mod.rs`, `src/sources/fake.rs`, all stubs |
|
||||
| [WS-A systemd](workstreams/WS-A-systemd.md) | 1 | P0 | `src/sources/systemd.rs`, `examples/systemd_dump.rs` |
|
||||
| [WS-B journal](workstreams/WS-B-journal.md) | 1 | P0 | `src/sources/journal.rs`, `examples/journal_tail.rs` |
|
||||
| [WS-C docker](workstreams/WS-C-docker.md) | 1 | P0 | `src/sources/docker.rs`, `examples/docker_ps.rs` |
|
||||
| [WS-D auth + DB](workstreams/WS-D-auth.md) | 1 | P0 | `src/db.rs`, `src/auth/`, `migrations/` |
|
||||
| [WS-E REST](workstreams/WS-E-rest.md) | 2 | P0 (fakes); A, B, C, D to finish | `src/api/` |
|
||||
| [WS-F MCP](workstreams/WS-F-mcp.md) | 2 | P0 (fakes); A, B, C, D to finish | `src/mcp/` |
|
||||
| [WS-G OTel](workstreams/WS-G-otel.md) | 2 | P0 (fakes); A, B, C to finish | `src/telemetry/`, `dev/otelcol.yaml` |
|
||||
| [P3 Integration](workstreams/P3-integration.md) | 3 | E, F, G | `src/main.rs` (wiring), `systemd/`, `README.md`, `tests/` |
|
||||
| [WS-I TLS](workstreams/WS-I-tls.md) | 4 | P3 | `src/tls.rs`, `server.tls` config keys, `tests/tls.rs` |
|
||||
| [WS-H NixOS](workstreams/WS-H-nixos.md) | 4 | P3, WS-I | `flake.nix`, `nix/` |
|
||||
|
||||
## Dependency graph
|
||||
|
||||
```
|
||||
P0 Foundation (config, DTOs, traits+fakes, AppState, stubs)
|
||||
├── WS-A systemd ──┐
|
||||
├── WS-B journal ──┤
|
||||
├── WS-C docker ───┼──► WS-E REST ──┐
|
||||
└── WS-D auth ─────┤ WS-F MCP ───┼──► P3 Integration
|
||||
└──► WS-G OTel ──┘
|
||||
|
||||
P3 Integration ──► WS-I TLS ──► WS-H NixOS (package + module + CLI + VM test)
|
||||
```
|
||||
|
||||
With source traits and fakes (DEC-2), Phase 2 cards can **start** as soon as P0 is done. They **finish** only once their real sources are merged and verified against a live host.
|
||||
|
||||
**Solo order:** P0 → A → B → C → D → E → F → G → P3.
|
||||
|
||||
## Rules
|
||||
|
||||
1. **Status flow:** `Backlog` → `Ready` → `In progress` → `Review` → `Done`, plus `Blocked` with a reason. A card becomes `Ready` when everything in its "Depends on" is `Done`, or when it can run against fakes.
|
||||
2. **One owner per card.** Put the name (or agent/branch) in the card's Owner field and on the board.
|
||||
3. **File ownership is strict.** A card edits only its owned files. If it needs a change in someone else's file, typically a DTO in `src/sources/mod.rs`, raise it in the card log and make the change as a small separate commit agreed with that file's owner.
|
||||
4. **Tick tasks in `TODO.md`.** Cards describe tasks but do not carry checkboxes, so there is one source of truth.
|
||||
5. **A card moves to `Done`** when every task is ticked, its "Done when" criteria are demonstrated, and `cargo clippy -- -D warnings` + `cargo test` pass.
|
||||
6. **Decisions go in `decisions.md`.** Record the outcome there and link it from the card log.
|
||||
7. **Branch naming:** `ws-a/systemd-source`, `p0/foundation`, and so on.
|
||||
1. Copy [`TEMPLATE.md`](TEMPLATE.md) to `plan/<short-name>.md` (for example `plan/phase-5-alerting.md`).
|
||||
2. Fill in:
|
||||
- **Goal**: what changes for users or operators, in a few sentences.
|
||||
- **Scope**: what is in, and explicitly what is out.
|
||||
- **Workstreams**: independent tracks with owned files, dependencies and done criteria, so they can run in parallel without merge conflicts.
|
||||
- **Open decisions**: questions that need a human call, each with options and a recommendation.
|
||||
- **Exit criteria**: how you will know the phase is done (commands to run, behaviour to demonstrate).
|
||||
3. Review and settle the open decisions in the plan file.
|
||||
4. When the plan is accepted, move the work into [`../TODO.md`](../TODO.md): add the phase milestone and one checklist per workstream with stable task IDs. Fold the accepted decisions into the Decisions section of [`../ARCHITECTURE.md`](../ARCHITECTURE.md).
|
||||
5. When the phase finishes, move the plan file (and any per-workstream notes) to `docs/workstreams/` as an archived record and collapse its tasks in `TODO.md` into the Completed table.
|
||||
Reference in new issue
Block a user