From 9869da5c6bcd77870bea8fd75a755a7044eb7989 Mon Sep 17 00:00:00 2001 From: sjat Date: Wed, 24 Jun 2026 16:16:25 +0200 Subject: [PATCH] docs(hardware): naming migration implementation plan --- .../2026-06-24-hardware-naming-migration.md | 207 ++++++++++++++++++ 1 file changed, 207 insertions(+) create mode 100644 notes/dev/plans/2026-06-24-hardware-naming-migration.md diff --git a/notes/dev/plans/2026-06-24-hardware-naming-migration.md b/notes/dev/plans/2026-06-24-hardware-naming-migration.md new file mode 100644 index 0000000..7ec0915 --- /dev/null +++ b/notes/dev/plans/2026-06-24-hardware-naming-migration.md @@ -0,0 +1,207 @@ +# Hardware Naming Migration Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Apply the approved hardware naming scheme by renaming the placeholder compute nodes `mf00`–`mf04` to `srv01`–`srv05`, recording cluster membership in frontmatter, and syncing the prose references — leaving all generated artifacts and the drift guard green. + +**Architecture:** Pure data + docs migration; **no generator logic changes**. The compute files are renamed (`git mv`), their `hostname:` field updated to match (the repo enforces filename-stem == `hostname`), `cluster: tappaas` added to the one known node, then `make docs-index` regenerates the hardware index and rack artifacts. Because `mf00`–`mf04` are referenced only by themselves (their `power:`/`links:` point outward to `pdu*`/`sw*`/`pp*`, with no reverse references), the rename cascades cleanly through regeneration. + +**Tech Stack:** Markdown frontmatter, Python generators (`gen_overview.py`, `gen_rack.py`) run via `make`, MkDocs Material, pytest. + +**Spec:** `notes/dev/specs/2026-06-24-hardware-naming-scheme.md`. + +## Global Constraints + +- **No code changes** to `scripts/*.py`, `tests/*`, `Makefile`, CI, `mkdocs.yml`, or `scripts/overview_config.yml`. The `cluster:` field is free-form frontmatter the generators ignore by design; it needs no enum or validation in this migration (the spec defers generator/grouping work). +- Identifier format per the scheme: ``, 2-digit zero-padded, unique within a kind, starting at `01`. Compute = `srv`. +- A renamed file's `hostname:` field MUST equal its new filename stem, or `gen_overview.py` fails (`filename stem != hostname`). +- Preserve each file's body and all other frontmatter unchanged — only `hostname:` changes (plus the one added `cluster:` line). +- `cluster:` values are provisional except the one known mapping: `srv01` (was `mf00`, "TaPPaaS node 1") → `cluster: tappaas`. Do **not** invent cluster values for `srv02`–`srv05`; leave the field off them until real assignments are given. +- `makerfloss.eu` (cloud FQDN) is untouched — it keeps its real hostname and gets no `cluster:`. +- Test-fixture hostnames in `tests/test_gen_rack.py` (synthetic `mf00`/`mf01` strings) and the historical phase specs/plans under `notes/dev/` are **out of scope** — they are illustrative/historical, not references to the renamed files. +- After each task: `make test` passes (49 tests, unaffected — fixtures are synthetic), `mkdocs build --strict` passes, and `make docs-check` exits 0. + +## Name mapping (this migration) + +| Old file | New file | `hostname:` | `cluster:` | +|----------|----------|-------------|------------| +| `mf00.md` | `srv01.md` | `srv01` | `tappaas` | +| `mf01.md` | `srv02.md` | `srv02` | (omit) | +| `mf02.md` | `srv03.md` | `srv03` | (omit) | +| `mf03.md` | `srv04.md` | `srv04` | (omit) | +| `mf04.md` | `srv05.md` | `srv05` | (omit) | + +--- + +### Task 1: Rename `mf00`–`mf04` → `srv01`–`srv05`, add cluster, regenerate + +**Files:** +- Rename: `docs/hardware/mf00.md`→`srv01.md`, `mf01.md`→`srv02.md`, `mf02.md`→`srv03.md`, `mf03.md`→`srv04.md`, `mf04.md`→`srv05.md` +- Modify (each renamed file): `hostname:` line; add `cluster: tappaas` to `srv01.md` +- Regenerate: `docs/hardware/index.md`, `docs/infrastructure/racks/rack01.md`, `docs/infrastructure/racks/rack01-elevation.svg` + +**Interfaces:** +- Consumes: `make docs-index` (runs `gen_overview.py` + `gen_rack.py`), `make test`, `make docs-check`, `mkdocs build --strict`. + +- [ ] **Step 1: Rename the five files with `git mv` (preserves history + body)** + +```bash +cd /home/sjat/Projects/MakerFLOSS +git mv docs/hardware/mf00.md docs/hardware/srv01.md +git mv docs/hardware/mf01.md docs/hardware/srv02.md +git mv docs/hardware/mf02.md docs/hardware/srv03.md +git mv docs/hardware/mf03.md docs/hardware/srv04.md +git mv docs/hardware/mf04.md docs/hardware/srv05.md +``` + +- [ ] **Step 2: Update the `hostname:` field in each renamed file** + +In each file, change the `hostname:` line (line 2) to match its new stem. Make exactly these five edits: + +- `docs/hardware/srv01.md`: `hostname: mf00` → `hostname: srv01` +- `docs/hardware/srv02.md`: `hostname: mf01` → `hostname: srv02` +- `docs/hardware/srv03.md`: `hostname: mf02` → `hostname: srv03` +- `docs/hardware/srv04.md`: `hostname: mf03` → `hostname: srv04` +- `docs/hardware/srv05.md`: `hostname: mf04` → `hostname: srv05` + +Do not change any other line in these files. + +- [ ] **Step 3: Add `cluster: tappaas` to `srv01.md` only** + +In `docs/hardware/srv01.md`, insert a `cluster: tappaas` line immediately after the `status: staging` line, so the top of the frontmatter reads: + +```yaml +--- +hostname: srv01 +kind: server +status: staging +cluster: tappaas +location: The pile +``` + +Leave `srv02.md`–`srv05.md` without a `cluster:` field. + +- [ ] **Step 4: Regenerate all indices and rack artifacts** + +Run: `make docs-index` +Expected: `gen_overview.py` rewrites `docs/hardware/index.md` (now listing `srv01`–`srv05` under Servers, no `mf0x`); `gen_rack.py` prints `Wrote rack01.md + rack01-elevation.svg (9 item(s))`. No `gen_overview` schema error (each stem now matches its `hostname`). + +- [ ] **Step 5: Confirm no `mf0x` remains anywhere under `docs/`** + +Run: `grep -rn -E "mf0[0-4]" docs/ ; echo "exit=$?"` +Expected: no matches, `exit=1` (grep found nothing). + +Run: `ls docs/hardware/srv0*.md | wc -l` +Expected: `5`. + +Run: `grep -n "cluster: tappaas" docs/hardware/srv01.md` +Expected: one match. + +- [ ] **Step 6: Run the full test suite** + +Run: `make test` +Expected: PASS (49 tests — the suite uses synthetic fixtures and is unaffected by the rename). + +- [ ] **Step 7: Build the site strictly** + +Run: `mkdocs build --strict` (if `mkdocs` is not on PATH, use `python3 -m mkdocs build --strict`) +Expected: build succeeds with no warnings-as-errors. The rack page and hardware index now show `srv01`–`srv05`. + +- [ ] **Step 8: Confirm the drift guard is satisfied** + +Run: `make docs-check` +Expected: exit 0 — committed artifacts match a fresh regeneration. + +- [ ] **Step 9: Commit** + +```bash +git add docs/hardware/ docs/infrastructure/racks/ +git commit -m "refactor(hardware): rename mf00-mf04 to srv01-srv05, add cluster field" +``` + +--- + +### Task 2: Sync prose references and record the scheme in CLAUDE.md + +**Files:** +- Modify: `CLAUDE.md` (stale hardware hint + new naming-scheme note) +- Modify: `README.md` (stale hardware hint) + +**Interfaces:** +- Consumes: `grep`, `make test`, `make docs-check` (sanity). + +- [ ] **Step 1: Fix the stale hardware hint in `CLAUDE.md`** + +In `CLAUDE.md`, change the repository-structure comment line: + +``` + hardware/ # auto-indexed per-host frontmatter (mf00..mf03, makerfloss.eu) +``` + +to: + +``` + hardware/ # auto-indexed per-host frontmatter (srv01..srv05, makerfloss.eu) +``` + +- [ ] **Step 2: Add a naming-scheme note to the `CLAUDE.md` working norms** + +In `CLAUDE.md`, immediately after the existing `- **Filenames**: …` bullet, add this new bullet: + +```markdown +- **Hardware identifiers**: `` — 2-digit, unique per kind (`srv`, `sw`, `pp`, `pdu`, `ups`, `shf`). Grouping (`cluster:`) lives in frontmatter, not the name. Full scheme: `notes/dev/specs/2026-06-24-hardware-naming-scheme.md`. +``` + +- [ ] **Step 3: Fix the stale hardware hint in `README.md`** + +In `README.md`, change the repository-layout comment line: + +``` + hardware/ # auto-indexed per-host frontmatter (mf00..mf03, makerfloss.eu) +``` + +to: + +``` + hardware/ # auto-indexed per-host frontmatter (srv01..srv05, makerfloss.eu) +``` + +- [ ] **Step 4: Confirm no stale `mf0x` hint remains in the two files** + +Run: `grep -n -E "mf0[0-4]" CLAUDE.md README.md ; echo "exit=$?"` +Expected: no matches, `exit=1`. + +Run: `grep -c "Hardware identifiers" CLAUDE.md` +Expected: `1`. + +- [ ] **Step 5: Sanity-check tests and drift still pass** + +Run: `make test` +Expected: PASS (49 tests). + +Run: `make docs-check` +Expected: exit 0 (CLAUDE.md/README.md are not generated artifacts, so this only confirms nothing regressed). + +- [ ] **Step 6: Commit** + +```bash +git add CLAUDE.md README.md +git commit -m "docs: record hardware naming scheme, refresh stale mf0x hints" +``` + +--- + +## Self-Review + +**Spec coverage (`2026-06-24-hardware-naming-scheme.md`):** +- Format ``, `srv` for compute — Task 1 (rename to `srv01`–`srv05`). ✔ +- Stable identifier + `cluster:` in frontmatter — Task 1 (rename + add `cluster: tappaas` to the one known node). ✔ +- `srv01` = `tappaas`; others provisional/omitted — Task 1 Step 3 + Global Constraints. ✔ +- `makerfloss.eu` FQDN exception untouched — Global Constraints (not in the rename set). ✔ +- No generator/grouping/validation work (deferred by spec) — Global Constraints (no `*.py`/config changes). ✔ +- Scheme discoverable to contributors — Task 2 (CLAUDE.md note + spec pointer). ✔ +- Stale prose hints corrected — Task 2 (CLAUDE.md + README.md). ✔ + +**Placeholder scan:** No "TBD"/"handle edge cases"/"similar to Task N". Cluster values for `srv02`–`srv05` are intentionally omitted (real-data dependency, explicitly bounded), not a placeholder. + +**Type consistency:** No code interfaces in this migration. The name mapping table (Task 1) and the `hostname:` edits (Step 2) are internally consistent: `mf00→srv01`, `mf01→srv02`, `mf02→srv03`, `mf03→srv04`, `mf04→srv05`, with `cluster: tappaas` on `srv01` only. Verification greps reference the same `srv0x` names produced by the edits.