Skip to content

Commit 91b74ae

Browse files
authored
docs: record dev container and PR template gotchas in CLAUDE.md (#25)
Four things cost time or caused a mistake during the repository rebuild and dependency catch-up, none of which were written down. pnpm install refuses to run in this container without CI=true, and then refuses again without --no-frozen-lockfile once a manifest has changed. Neither is guessable from the error text. Prettier re-pads markdown tables, so editing one cell in the CI table breaks format:check in a way that looks unrelated to the edit. A devcontainers bump is the one dependency class CI cannot verify, since nothing in CI builds the container. The ghcr manifest carries the feature's option schema, which is enough to check compatibility without a rebuild. The PR template section names changed in #19, and four PRs were written against the old ones because CLAUDE.md only said the template is filled in automatically.
1 parent a8dd48e commit 91b74ae

1 file changed

Lines changed: 22 additions & 0 deletions

File tree

CLAUDE.md

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,23 @@ pnpm lint # oxlint
5050
- When killing dev servers with `pkill -f`, use a self-excluding pattern such as
5151
`pgrep -f 'Vox[L]ib'`; a plain `-f VoxLib.Api` also matches the shell running
5252
the command and kills it.
53+
- `pnpm install` aborts with `ERR_PNPM_ABORTED_REMOVE_MODULES_DIR_NO_TTY` when it
54+
decides to purge `node_modules` and has no TTY to ask. Prefix with `CI=true`.
55+
Add `--no-frozen-lockfile` when a manifest changed, because `CI=true` also makes
56+
frozen-lockfile the default and the install then fails a second time.
57+
- Prettier owns `CLAUDE.md` and `README.md`, table alignment included. Editing one
58+
cell widens the column and `pnpm format:check` fails until
59+
`pnpm exec prettier --write <file>` re-pads the whole table.
60+
- Nothing in CI builds the dev container, so a `devcontainers` dependency bump is
61+
unverified by a green PR. Compare the feature's options across versions without
62+
a rebuild:
63+
64+
```bash
65+
TOKEN=$(curl -s "https://ghcr.io/token?scope=repository:devcontainers/features/node:pull&service=ghcr.io" | jq -r .token)
66+
curl -s -H "Authorization: Bearer $TOKEN" -H "Accept: application/vnd.oci.image.manifest.v1+json" \
67+
https://ghcr.io/v2/devcontainers/features/node/manifests/2.1.0 \
68+
| jq -r '.annotations["dev.containers.metadata"]' | jq .options
69+
```
5370

5471
## What this project is
5572

@@ -92,6 +109,11 @@ PR is where CI runs and where the change becomes reviewable later; a commit
92109
pushed straight to `main` skips both. `.github/pull_request_template.md` is
93110
filled in automatically.
94111

112+
Fill in the sections that `.github/pull_request_template.md` actually has, and read
113+
it rather than copying an older PR. They have already changed once, from
114+
What / Why / How / Checklist to Summary / Changes / Out of scope / Test plan /
115+
Dependencies.
116+
95117
**Merge by squashing.** A squash merge collapses every commit on the branch into
96118
a single commit on `main`. It means you can commit as messily as you like while
97119
working ("wip", "fix typo", "actually fix it") and `main` still reads as one

0 commit comments

Comments
 (0)