dtoro
543745cad9
- infrastructure/network.md: permanent topology reference — VLAN 1 (main LAN) + VLAN 10 (homelab 192.168.8.0/24), Fritz!Box 7590 as VLAN router, SODOLA 5-Port 2.5Gbit as homelab switch - plans/2026-06-01-slate-ax-to-sodola-migration.md: full migration runbook (pre-flight, Fritz!Box second-network config, SODOLA VLAN table, cutover procedure, verification commands). Gateway 192.168.8.1 is unchanged — no LXC/VM config edits needed. Fritz!Box DHCP for VLAN 10 hands out 192.168.8.2 (Technitium CT 107) as DNS, closing the outstanding item in dns.md. - plans/index.md: establishes plans/ convention (Planned → In Progress → Done) - CONTRIBUTING.md: plan page template + linking discipline for plans Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
124 lines
2.6 KiB
Markdown
124 lines
2.6 KiB
Markdown
# Contributing to the Homelab Wiki
|
|
|
|
## Voice
|
|
|
|
Concise, technical, sysadmin-to-sysadmin. No marketing prose, no exclamation marks.
|
|
|
|
## Page templates
|
|
|
|
### Container page (`containers/<id>-<name>.md`)
|
|
|
|
```markdown
|
|
# <id> — `<name>`
|
|
|
|
One-sentence purpose.
|
|
|
|
## At a glance
|
|
- **Hostname:** `<name>`
|
|
- **IP:** `192.168.8.x`
|
|
- **Privilege:** privileged | unprivileged
|
|
- **Resources:** N cores / M GiB RAM / D GiB rootfs
|
|
- **Mounts:** `/mnt/library` ↔ `/mnt/library` (if any)
|
|
- **Public hostname:** `<sub>.hubris.network` (if proxied)
|
|
|
|
## Role
|
|
What it does, what it talks to.
|
|
|
|
## Service / port map
|
|
| Service | Listen | Notes |
|
|
|
|
## Storage / config paths
|
|
|
|
## Auto-deploy
|
|
(if any) — link to [auto-deploy](../infrastructure/auto-deploy.md)
|
|
|
|
## Related
|
|
- [Caddy](121-caddy.md) (if proxied)
|
|
- [DNS](../infrastructure/dns.md) (if has subdomain)
|
|
- [Authentik](124-authentik.md) (if SSO)
|
|
- ...
|
|
|
|
## Changelog
|
|
### YYYY-MM-DD — short title
|
|
What changed, why, link to investigation if any.
|
|
```
|
|
|
|
### Cross-cutting page (`infrastructure/<topic>.md`)
|
|
|
|
```markdown
|
|
# <Topic>
|
|
|
|
One-sentence summary.
|
|
|
|
## Why
|
|
Design rationale — what it replaces, what it solves.
|
|
|
|
## Components
|
|
Where it runs, what files matter.
|
|
|
|
## How to apply / use
|
|
Recipes.
|
|
|
|
## Gotchas
|
|
|
|
## Related
|
|
Links to nodes that host or depend on this.
|
|
|
|
## Changelog
|
|
```
|
|
|
|
### Plan (`plans/YYYY-MM-DD-slug.md`)
|
|
|
|
```markdown
|
|
# YYYY-MM-DD — <title>
|
|
|
|
## Goal
|
|
What this change achieves and why.
|
|
|
|
## Current topology / state
|
|
Diagram or description of what exists now.
|
|
|
|
## Target topology / state
|
|
What it looks like after.
|
|
|
|
## Pre-flight checklist
|
|
|
|
## Step-by-step procedure
|
|
|
|
## Verification
|
|
|
|
## Post-migration
|
|
Changelog entries to write, index status to update.
|
|
```
|
|
|
|
### Investigation (`investigations/YYYY-MM-DD-slug.md`)
|
|
|
|
```markdown
|
|
# YYYY-MM-DD — <title>
|
|
|
|
## Summary
|
|
1-3 sentences.
|
|
|
|
## Timeline
|
|
|
|
## Root cause
|
|
|
|
## Mitigations applied
|
|
|
|
## Open questions
|
|
```
|
|
|
|
## Linking discipline
|
|
|
|
- Every container page links to every cross-cutting page it participates in.
|
|
- Every cross-cutting page lists the nodes that participate.
|
|
- Every investigation links to the nodes it implicates *and* gets back-linked from each node's changelog.
|
|
- Every plan links to the infrastructure pages it affects. When done, update the plan's status in `plans/index.md` and write changelog entries on affected node pages.
|
|
|
|
## Changelog hygiene
|
|
|
|
- Reverse-chronological (newest first).
|
|
- One entry per discrete change, even if you make several in one day.
|
|
- If a change spans nodes, repeat the entry on each affected page (different perspective is fine).
|
|
- Don't rewrite history — entries are append-only. Mistakes get a follow-up entry that supersedes them.
|