From 9d7b4684c4567ba7f618f39d3f44a5c42efb31ff Mon Sep 17 00:00:00 2001 From: sjat Date: Mon, 29 Jun 2026 21:40:09 +0200 Subject: [PATCH] docs: publish hardware naming scheme and link it from the editing guide Move the naming-scheme spec from notes/dev/specs/ into docs/guides/ so it publishes to docs.makerfloss.eu, add it under the Hardware nav, and link it from the editing guide. Repoint the stale references in CLAUDE.md and the migration plan to the new path. Co-Authored-By: Claude Opus 4.8 (1M context) --- CLAUDE.md | 2 +- docs/guides/editing-hardware-docs.md | 8 +++++--- .../guides/hardware-naming-scheme.md | 0 mkdocs.yml | 1 + notes/dev/plans/2026-06-24-hardware-naming-migration.md | 6 +++--- 5 files changed, 10 insertions(+), 7 deletions(-) rename notes/dev/specs/2026-06-24-hardware-naming-scheme.md => docs/guides/hardware-naming-scheme.md (100%) diff --git a/CLAUDE.md b/CLAUDE.md index 2d9a20c..80bd579 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -18,7 +18,7 @@ From `notes/todo/2026-04-14-todo.md`: - **Decisions**: Lightweight markdown decision logs - **License**: FLOSS by default - **Filenames**: ASCII lowercase, kebab-case (`like-this.md`), English regardless of content language. Dated docs use an ISO prefix joined with a hyphen: `YYYY-MM-DD-label.md`. Hostnames are the exception — `docs/hardware/*.md` must equal the host's `hostname` (enforced by `scripts/gen_overview.py`). -- **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`. +- **Hardware identifiers**: `` — 2-digit, unique per kind (`srv`, `sw`, `pp`, `pdu`, `ups`, `shf`). Grouping (`cluster:`) lives in frontmatter, not the name. Full scheme: `docs/guides/hardware-naming-scheme.md`. ## Repository Structure diff --git a/docs/guides/editing-hardware-docs.md b/docs/guides/editing-hardware-docs.md index afecb9f..0fcb0bd 100644 --- a/docs/guides/editing-hardware-docs.md +++ b/docs/guides/editing-hardware-docs.md @@ -19,8 +19,9 @@ graph — is **generated** from that frontmatter. ## Quick start: add a device -1. Pick a hostname following the scheme `` — a 2-digit number, - unique per kind (`srv`, `sw`, `pp`, `pdu`, `ups`, `shf`, …). Example: `srv06`. +1. Pick a hostname following the [naming scheme](hardware-naming-scheme.md): + `` — a 2-digit number, unique per kind (`srv`, `sw`, `pp`, + `pdu`, `ups`, `shf`, …). Example: `srv06`. 2. Create `docs/hardware/.md`. **The filename stem must equal the `hostname` field** — `srv06.md` must contain `hostname: srv06`. 3. Fill in the frontmatter (see the reference below). Write any free-text under @@ -175,7 +176,8 @@ check fails and nothing is published. !!! success "Do" - **Do** run `make docs-index` and commit the regenerated files with your change. - **Do** keep the filename equal to the `hostname`. - - **Do** use the `` naming scheme, 2 digits, unique per kind. + - **Do** use the [`` naming scheme](hardware-naming-scheme.md), + 2 digits, unique per kind. - **Do** mark unknown values as provisional placeholders and ask before inventing rack/power/network numbers. - **Do** preview locally with `make docs-serve` before pushing. diff --git a/notes/dev/specs/2026-06-24-hardware-naming-scheme.md b/docs/guides/hardware-naming-scheme.md similarity index 100% rename from notes/dev/specs/2026-06-24-hardware-naming-scheme.md rename to docs/guides/hardware-naming-scheme.md diff --git a/mkdocs.yml b/mkdocs.yml index f5caef5..42298bf 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -60,6 +60,7 @@ nav: - Hardware: - hardware/index.md - Editing the hardware docs: guides/editing-hardware-docs.md + - Naming scheme: guides/hardware-naming-scheme.md - Services: - services/index.md - Infrastructure: diff --git a/notes/dev/plans/2026-06-24-hardware-naming-migration.md b/notes/dev/plans/2026-06-24-hardware-naming-migration.md index 7ec0915..f2480dd 100644 --- a/notes/dev/plans/2026-06-24-hardware-naming-migration.md +++ b/notes/dev/plans/2026-06-24-hardware-naming-migration.md @@ -8,7 +8,7 @@ **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`. +**Spec:** `docs/guides/hardware-naming-scheme.md`. ## Global Constraints @@ -149,7 +149,7 @@ to: 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`. +- **Hardware identifiers**: `` — 2-digit, unique per kind (`srv`, `sw`, `pp`, `pdu`, `ups`, `shf`). Grouping (`cluster:`) lives in frontmatter, not the name. Full scheme: `docs/guides/hardware-naming-scheme.md`. ``` - [ ] **Step 3: Fix the stale hardware hint in `README.md`** @@ -193,7 +193,7 @@ git commit -m "docs: record hardware naming scheme, refresh stale mf0x hints" ## Self-Review -**Spec coverage (`2026-06-24-hardware-naming-scheme.md`):** +**Spec coverage (`docs/guides/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. ✔