irene
be81469c7c
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.
90 lines
3.5 KiB
Markdown
90 lines
3.5 KiB
Markdown
# Video-related files for NCMR songs
|
|
|
|
This repo houses the code-like files for NCMR music videos. Binary assets live elsewhere.
|
|
|
|
## Structure
|
|
|
|
> **Repo state: workspace under construction.** `master` is *not* locked in yet —
|
|
> it is still being assembled as the shared template. Until it is locked, any
|
|
> branching strategy is fine and template/tooling work can land on `master`
|
|
> directly. The branch conventions below describe the intended end state, not a
|
|
> rule currently in force.
|
|
|
|
### `master` branch — shared template
|
|
|
|
This branch holds the common scaffolding:
|
|
|
|
- **Remotion project** — entry point, root component, and a placeholder composition
|
|
- **`scripts/`** — Python toolchain (stdlib only) for subtitles, ffmpeg and asset manifests
|
|
- **Build config** — TypeScript, ESLint, Prettier, Remotion studio
|
|
|
|
### `src/` vs `scripts/`
|
|
|
|
Two directories, two jobs:
|
|
|
|
- **`src/`** — Remotion input only. Everything here is compiled by `tsc`/Remotion
|
|
and linted by `npm run lint`.
|
|
- **`scripts/`** — operator tooling. Python, standard library only, run directly
|
|
(`python3 scripts/tools.py --help`). Nothing here is part of the Remotion build.
|
|
|
|
Keep the boundary sharp: anything the video build compiles belongs in `src/`, and
|
|
anything you run by hand belongs in `scripts/`.
|
|
|
|
### Song branches
|
|
|
|
For each song, create a branch `<song-name>/master` (and optionally feature branches
|
|
like `<song-name>/synced-lyrics-remotion`):
|
|
|
|
```
|
|
git checkout -b <song-name>/master
|
|
```
|
|
|
|
Copy the shared template into the song branch, then add song-specific files:
|
|
|
|
```
|
|
mkdir -p <song-name>
|
|
# Place your song-specific compositions, assets manifests, etc.
|
|
```
|
|
|
|
Once `master` is locked in it remains protected and mostly immutable. Until then,
|
|
song branches are a rehearsal for that end state, not a requirement.
|
|
|
|
## Guideline
|
|
|
|
### Git-ignored (not tracked here)
|
|
|
|
- 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)
|
|
- `<song>/master` — song-specific work
|
|
- `<song>/<feature>` — parallel features for a song
|
|
|
|
Once `master` is locked, this repo's branching rules supersede any generic git
|
|
operation conventions. Before that point, use whatever is convenient.
|