Background
PR #287 (cb44b56, Fix 5) gitignored the 78 generated examples/ outputs with
open-ended catch-alls plus a fixed negation list:
examples/**/*.md
!examples/**/README.md
examples/**/*.json
!examples/**/package.json
!examples/**/mds.json
!examples/**/vars.json
!examples/**/vars-minimal.json
!examples/**/tsconfig.json
.gitignore:22-32 already carries an accurate FOOTGUN WARNING describing the
consequence. This issue tracks closing it structurally rather than by comment.
Problem
Any newly hand-authored .md or .json under examples/ is silently
ignored unless someone remembers to add a matching ! exception first. The
failure is invisible in the worst way: git add reports nothing, git status
shows a clean tree, the file is simply absent from the commit, and the author
discovers it only when a fresh clone is missing an example.
CI structurally cannot catch this. The examples-gitignore-coverage job
added in PR #287 asserts the inverse property — that after mds build, no
generated output is left untracked. A hand-authored file that was never
committed does not exist in a CI checkout, so no job can observe its absence.
This is currently local discipline only, on a directory that is the project's
primary onboarding surface.
Proposed change
Two options; (a) is the structural fix, (b) is the cheap mitigation.
(a) Generate into a dedicated output directory. Have mds build write
example outputs to e.g. examples/**/out/ (or a top-level target/examples/)
and ignore only that path. examples/**/*.md stops being a catch-all, every
hand-authored file under examples/ becomes tracked by default, and the footgun
is designed out rather than documented. Costs: the example READMEs and the
examples-gitignore-coverage job both need updating, and side-by-side
.mds/.md output is arguably nicer for readers browsing on GitHub.
(b) Pre-commit check. A hook that runs
git status --porcelain --ignored=matching -- examples/ and warns when an
ignored examples/ file has no sibling .mds source — the signature of a
hand-authored file caught by a catch-all. This is exactly the check the original
examples-guard job attempted; it is meaningless in CI (fresh checkout, no such
files) but meaningful locally, which is precisely where the footgun fires. Pairs
naturally with the control-byte pre-commit hook.
Acceptance Criteria
Reference
Background
PR #287 (
cb44b56, Fix 5) gitignored the 78 generatedexamples/outputs withopen-ended catch-alls plus a fixed negation list:
.gitignore:22-32already carries an accurate FOOTGUN WARNING describing theconsequence. This issue tracks closing it structurally rather than by comment.
Problem
Any newly hand-authored
.mdor.jsonunderexamples/is silentlyignored unless someone remembers to add a matching
!exception first. Thefailure is invisible in the worst way:
git addreports nothing,git statusshows a clean tree, the file is simply absent from the commit, and the author
discovers it only when a fresh clone is missing an example.
CI structurally cannot catch this. The
examples-gitignore-coveragejobadded in PR #287 asserts the inverse property — that after
mds build, nogenerated output is left untracked. A hand-authored file that was never
committed does not exist in a CI checkout, so no job can observe its absence.
This is currently local discipline only, on a directory that is the project's
primary onboarding surface.
Proposed change
Two options; (a) is the structural fix, (b) is the cheap mitigation.
(a) Generate into a dedicated output directory. Have
mds buildwriteexample outputs to e.g.
examples/**/out/(or a top-leveltarget/examples/)and ignore only that path.
examples/**/*.mdstops being a catch-all, everyhand-authored file under
examples/becomes tracked by default, and the footgunis designed out rather than documented. Costs: the example READMEs and the
examples-gitignore-coveragejob both need updating, and side-by-side.mds/.mdoutput is arguably nicer for readers browsing on GitHub.(b) Pre-commit check. A hook that runs
git status --porcelain --ignored=matching -- examples/and warns when anignored
examples/file has no sibling.mdssource — the signature of ahand-authored file caught by a catch-all. This is exactly the check the original
examples-guardjob attempted; it is meaningless in CI (fresh checkout, no suchfiles) but meaningful locally, which is precisely where the footgun fires. Pairs
naturally with the control-byte pre-commit hook.
Acceptance Criteria
examples/foo/notes.mdadded without a!exception issurfaced to the author before commit (or is tracked by default under (a))
examples-gitignore-coverageCI job still passes.gitignore's FOOTGUN WARNING is updated or removed to match the new reality.gitignoreupdated; output paths documentedReference
cb44b56) Fix 5 — introduced the catch-alls.gitignore:22-32— the FOOTGUN WARNING this issue proposes to make unnecessary.github/workflows/ci.yml:228-276—examples-gitignore-coverage, whichcovers the inverse property only