docs: add ARMADILHAS.md, the project-wide index of gotchas - #71
Merged
Conversation
The gotcha index existed only on a private working branch, so the public repo carried none of it — including the nested-form trap fixed in v1.38.6, whose whole point is to stop the next person repeating it. Brings over the entries that describe public code (deploy, versioning, gunicorn, Bootstrap Icons, templates). Entries about hardware work that lives outside this repo stay out, since their file:line pointers would not resolve here. Two pointers were repaired on the way: both cited CLAUDE.md, which is gitignored in this repo, so a public reader could never follow them. Docs only — no version bump, nothing user-visible changed. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
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
1 participant
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.
Why
The gotcha index (
docs/ARMADILHAS.md) existed only on a private working branch and had never been onmain. The public repo therefore carried none of it — including the nested-form trap fixed in #70, whose entire purpose is to keep the next person from repeating it.What comes over
The entries that describe public code: the
update-lxc.shself-update ordering, version-number reuse after a revert, the nested<form>trap,git describelying on a stale branch, gunicorn--preload, the missingbi-balance-scaleicon, tooltips on disabled buttons, and the untrackedstatic/brands/+spool.env.Entries whose
file:linepointers reference work living outside this repository are left out — a pointer that cannot be followed is worse than no entry, which is the doctrine this file itself is written under.Two pointers repaired
Two entries cited
CLAUDE.mdas their reference. That file is gitignored here (.gitignore:13), so a reader of the public repo could never follow either one. They now point at the code and the concrete path instead.Not a release
Docs only — no
VERSIONbump and noCHANGELOG.mdentry, since nothing user-visible changed.🤖 Generated with Claude Code