Repository navigation
docs: split repo docs and wiki on a stated rule; move host runbooks to the wiki - #133
Merged
Merged
Conversation
The two Docker disk documents added in #123 describe Docker Desktop's settings-store.json, the vscode volume and a Mac's free space. Nothing in this repo can invalidate them; they go stale when Docker Desktop changes. Keeping them in-tree meant they were reviewed on this repo's cadence for no benefit, and edited through branch -> PR -> CI at exactly the moment you least want that: during an incident, with a full disk. Moved to the wiki as "Docker Disk Maintenance" and "Incident: Docker Disk Exhaustion (2026-09-07)", with their relative cross-links rewritten and Sources footers citing #123. README keeps its entries, repointed. The rule that decided it is now in .claude/CLAUDE.md rather than left implicit: a document that goes stale when this repo's code changes belongs in the repo; one that goes stale when an external system changes, or that spans several images, belongs in the wiki. That is why per-image READMEs do not move -- a tag list has to change in the same commit as its Dockerfile, and splitting them guarantees drift. The wiki gains three consumer-facing pages in the same pass (Choosing an Image, Image Tags and Rebuild Policy, Troubleshooting), so README now points there for cross-image questions no single README owns. Tradeoff accepted: the moved content is no longer reviewed in a PR and no longer in this repo's git log. It has its own history in the wiki repo, and it has zero coupling to code here, so nothing that could drift does.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Follow-up to #123. Establishes the boundary between this repo's docs and its wiki, and moves the two documents that were on the wrong side of it.
The rule
Now recorded in
.claude/CLAUDE.md, so it doesn't get re-litigated every time a doc is added.The test does real work. It says per-image READMEs must not move: a tag list or tool table has to change in the same commit as the Dockerfile it describes, and splitting them guarantees drift. It says
docs/disk-usage.mdanddocs/docker-maintenance-cheatsheet.mdshould move: they describe Docker Desktop'ssettings-store.json, thevscodevolume and a Mac's free space, and nothing in this repo can invalidate them.What moved
docs/docker-maintenance-cheatsheet.mddocs/disk-usage.mdKept as two pages rather than merged — the cheatsheet is action-first, the incident writeup is the why, and collapsing them buries the commands you need at 2am. Their relative cross-links (
./disk-usage.md) were rewritten to wiki links, which would otherwise have 404'd.The README's two entries are kept and repointed, so the discovery path is unchanged.
What the wiki gained in the same pass
Three consumer-facing pages, because a public repo's wiki should be useful to people using the images, not just to me:
bun,hugo-bun, …, where the image is the toolchain and the tag says so) versus bring-your-own-toolchain (claude-code, which ships mise but not the tools).:latestmoves when Renovate bumps a tool, thatclaude-code:<git-sha>is the only immutable tag published here, or that three of the four tracked tools soak for three days while claude-code does not.rtkname collision, auth, disk), each citing its issue. Anything image-specific stays in that image's README.Plus
_Sidebar.mdfor navigation, and a rewrittenHomecarrying the rule and a no-duplication policy: wiki links to READMEs, READMEs link back, and if the same fact appears in both then one is wrong.Sources on every page
Each wiki page now ends with a
## Sourcessection citing the PRs and issues its knowledge came from, and a*Last verified:*date. Wiki pages rot silently and have no CI; the date is the cheapest available signal.Tradeoff being accepted
The moved content is no longer reviewed through a PR, no longer in this repo's
git log, and a future change can't update code and that doc in one commit. It has its own history in the wiki's git repo, and it has zero coupling to code here — so nothing that could drift does. That would not be free for anything describing an image, which is exactly why nothing else moved.Verification
Home301s to the wiki root, as it should).grepfordisk-usage/docker-maintenance-cheatsheetacross the tree: only the two files' own cross-references, both removed with them.docs/*.mdfromREADME.md.Follow-up