docs(hardware): naming migration implementation plan
This commit is contained in:
sjat
parent
bcd5748d28
commit
9869da5c6b
1 changed files with 207 additions and 0 deletions
207
notes/dev/plans/2026-06-24-hardware-naming-migration.md
Normal file
207
notes/dev/plans/2026-06-24-hardware-naming-migration.md
Normal file
|
|
@ -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: `<kind-abbrev><NN>`, 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**: `<kind-abbrev><NN>` — 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 `<kind-abbrev><NN>`, `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.
|
||||||
Loading…
Add table
Reference in a new issue