oikos/CONTRIBUTING.md

# 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.

## Same-session update rule

When you make a change to a node — migrate an LXC, update an IP, change a
mount, deploy a new service — **update every relevant doc page in the same
session.** A change that touches a container page must also update:

- The `containers/index.md` table (IPs, host, mounts, status)
- The `README.md` table (if the change affects listed columns)
- The Caddy page site list (if the change affects `*.hubris.network` routing)
- The DNS / ingress infrastructure pages (if the change affects routing)
- The `hosts/{hubris,strong}.md` host page (if container count changes)
- The `inventory.yaml` host entry (source of truth for the `hosts/*.yaml` generation)
- The `infrastructure/topology.md` (generated from inventory, but regen if needed)

The pattern of updating only one page and leaving stale references on others
is a bug. If you're doing a multi-step migration, document the intermediate
state with a changelog entry that says "pending — will finalize after Phase
N."

This rule is why Phase 2 of the strong migration (2026-07-05) caused
widespread stale data: individual container pages were updated in the
changelog but never had their At-a-glance sections, IPs, mount paths, or
host attribution updated. Don't repeat that.