From be81469c7c92178374d34b04c035e5045c4f8b37 Mon Sep 17 00:00:00 2001 From: Irene Date: Thu, 10 Sep 2026 23:11:25 +0900 Subject: [PATCH] chore: ignore package-lock.json, and record why Work happens on both Windows and Linux, so a committed lockfile would do harm rather than good here: - Every dependency in package.json is pinned exactly (no ^ or ~), so a lockfile has no floating ranges to guard. A plain `npm install` resolves identically without it. - The lock records platform-specific optional binaries for whichever OS built it (@rollup/rollup-linux-x64-gnu vs -win32-x64-msvc, for instance). Committed from one platform it is wrong on the other, and `npm ci` refuses rather than adapting, since reproducing the recorded tree exactly is its entire purpose. That is a strict mechanism pointed at the wrong target: it would break installs across machines while guaranteeing versions that were already exact. Cloning is rare here, so the reproducibility upside is small and the cross-platform cost is immediate. Both .gitignore and README now state the reasoning, including when to revisit (a dependency loosened to a range, or transitive drift exact pinning cannot control). Silently ignoring it would have invited the same question again. Verified: `git check-ignore -v package-lock.json` matches, and a regenerated lockfile leaves `git status` clean. --- .gitignore | 11 +++++++++++ README.md | 20 ++++++++++++++++++++ 2 files changed, 31 insertions(+) diff --git a/.gitignore b/.gitignore index b8c9b27..c0dd7b2 100644 --- a/.gitignore +++ b/.gitignore @@ -36,7 +36,18 @@ node_modules dist out .env + # Python (helper scripts) __pycache__/ *.py[cod] .venv/ + +# Package lock — deliberately NOT tracked. +# Every dependency in package.json is pinned to an exact version (no ^ or ~), so +# a lockfile has no floating ranges to guard against. What it would add instead is +# trouble across machines: the lock captures the resolved tree including +# platform-specific optional binaries (e.g. @rollup/rollup-linux-x64-gnu), so a +# Linux-generated lock is wrong on Windows and vice versa, and `npm ci` refuses +# outright when the lock and manifest disagree. Revisit this if a dependency is +# ever loosened to a range or picks up meaningful transitive drift. +package-lock.json diff --git a/README.md b/README.md index 14944d6..4ccd65e 100644 --- a/README.md +++ b/README.md @@ -55,10 +55,30 @@ song branches are a rehearsal for that end state, not a requirement. - Binary input assets (audio, images, fonts, material video clips) - Video output (`out/`, rendered files) +- `package-lock.json` — see below For untracked input assets, a **bill of materials** listing everything and explaining what each file is will be mandatory. Keep it as `BOM.md` alongside your song assets. +### Why there is no `package-lock.json` + +Deliberate, not an oversight. Work happens on both Windows and Linux, and two +things make a lockfile a liability here rather than a safeguard: + +1. **There is nothing for it to pin.** Every dependency in `package.json` is + pinned to an exact version — no `^`, no `~`. A plain `npm install` on any + machine resolves to the same versions the lockfile would have recorded. +2. **A lockfile is platform-specific.** It records the resolved tree, including + the optional native binaries for whichever OS generated it (`@rollup/rollup-linux-x64-gnu`, + `@rollup/rollup-win32-x64-msvc`). Committed from Linux it is wrong on Windows, + and `npm ci` refuses outright rather than adapting, since its whole purpose is + to reproduce the recorded tree exactly. + +So it would be strict about the wrong thing: breaking installs across machines +while guarding versions that were never floating. Revisit this if a dependency is +ever loosened to a range, or picks up transitive drift that exact pinning cannot +control — at that point the lockfile earns its friction. + ### Branching - `master` — minimal template (protected once locked in)