|
| 1 | +# Repository Guidelines |
| 2 | + |
| 3 | +## Dos and Don'ts |
| 4 | + |
| 5 | +- Do run Node.js version updates through `./update.sh` so Dockerfiles, musl checksums, and Yarn pins stay synchronized with the templates in `Dockerfile-*.template` and helpers in `functions.sh`. |
| 6 | +- Do refresh signing keys with `./update-keys.sh` whenever upstream release keys change; the script keeps `keys/node.keys` aligned with <https://github.com/nodejs/node#release-keys>. |
| 7 | +- Do consult `versions.json`, `architectures`, and `config` before adding or removing variants so metadata consumed by `stackbrew.js` and CI stays coherent. |
| 8 | +- Don't diverge any per-variant `docker-entrypoint.sh` from the root copy—automation expects identical logic across `*/docker-entrypoint.sh`. |
| 9 | +- Don't merge Alpine Dockerfiles with placeholder `CHECKSUM=""`; populate the musl checksum so `.github/workflows/missing-checksum.yml` passes. |
| 10 | +- Don't skip formatting and static analysis for shell changes; `.github/workflows/shfmt.yml` enforces `shfmt -sr -i 2 -ci` and `shellcheck` on every `*.sh`. |
| 11 | + |
| 12 | +## Project Structure and Module Organization |
| 13 | + |
| 14 | +- The root folders `20/`, `22/`, `24/`, and `25/` group Docker image definitions by major Node.js release; each variant directory (for example `22/bookworm` or `24/alpine3.22`) contains a `Dockerfile` and a scoped copy of `docker-entrypoint.sh`. |
| 15 | +- Shared templates (`Dockerfile-alpine.template`, `Dockerfile-debian.template`, `Dockerfile-slim.template`) feed `update.sh` when generating or refreshing Dockerfiles. |
| 16 | +- Global metadata lives in `config`, `architectures`, and `versions.json`; helper logic in `functions.sh` reads these files to resolve defaults, supported variants, and tagging. |
| 17 | +- Release automation and maintenance tooling reside at the repository root: `update.sh`, `update-keys.sh`, `stackbrew.js`, `build-automation.mjs`, `genMatrix.js`, and `docker-entrypoint.sh`. |
| 18 | +- Continuous integration workflows are in `.github/workflows/`, notably `build-test.yml`, `automatic-updates.yml`, `official-pr.yml`, `shfmt.yml`, `doctoc.yml`, and `markdown-link-check.yml`. |
| 19 | +- Project-wide documentation and policies live in `README.md`, `docs/BestPractices.md`, `CONTRIBUTING.md`, `GOVERNANCE.md`, and `SECURITY.md`. |
| 20 | + |
| 21 | +## Build, Test, and Development Commands |
| 22 | + |
| 23 | +- Targeted image builds use the Docker CLI; for example `docker build -t node-local -f 22/bookworm/Dockerfile .` exercises the `22/bookworm` variant without touching other directories. |
| 24 | +- After building, validate the entrypoint and runtime with `docker run --rm node-local node --version` and compare the output to the `ENV NODE_VERSION` in the edited `Dockerfile`. |
| 25 | +- Use `./update.sh -h` to review options, then run commands such as `./update.sh 22` or `./update.sh 22 alpine3.22` to regenerate Dockerfiles and checksums; see `update.sh` for full behavior. |
| 26 | +- Regenerate the official manifest with `node stackbrew.js > library/node` before proposing downstream updates; the script consumes `versions.json` and the tracked Dockerfiles. |
| 27 | +- Documentation checks mirror CI: `doctoc --title='## Table of Contents' --github README.md` (see `.github/workflows/doctoc.yml`) and `markdown-link-check -c markdown_link_check_config.json README.md` (see `.github/workflows/markdown-link-check.yml`). |
| 28 | + |
| 29 | +## Coding Style and Naming Conventions |
| 30 | + |
| 31 | +- Follow `.editorconfig`: UTF-8 files, LF endings, 2-space indentation, trimmed trailing whitespace, and final newlines. |
| 32 | +- Shell scripts must format with `shfmt -sr -i 2 -ci` and stay `shellcheck` clean, matching `.github/workflows/shfmt.yml`; prefer POSIX `sh`-compatible syntax unless a script explicitly requires Bash. |
| 33 | +- Dockerfiles should inherit structure from the templates, keeping instruction order (user creation, `ENV` blocks, checksum verification, smoke tests) consistent across variants. |
| 34 | +- Keep duplicated `docker-entrypoint.sh` files byte-for-byte with the root copy; apply any edits everywhere to avoid drift. |
| 35 | +- Markdown documents rely on Doctoc headers and the shared link-check configuration; keep generated TOCs aligned with `.github/workflows/doctoc.yml`. |
| 36 | + |
| 37 | +## Testing Guidelines |
| 38 | + |
| 39 | +- Lean on focused Docker builds for regression checks: rebuild only the touched `*/Dockerfile` directories and run the smoke commands from `.github/workflows/build-test.yml` (`node --version`, `npm --version`, `yarn --version`) inside the resulting image. |
| 40 | +- When modifying Alpine variants, verify the musl tarball checksum resolves to the populated `CHECKSUM` value before pushing changes. |
| 41 | +- Re-run documentation tooling (`doctoc`, `markdown-link-check`) whenever Markdown files change so local output matches CI expectations. |
| 42 | +- Update signing keys or automation scripts only after validating dependent commands (`./update.sh`, `./stackbrew.js`) complete without errors in your environment. |
| 43 | + |
| 44 | +## Commit and Pull Request Guidelines |
| 45 | + |
| 46 | +- Follow `CONTRIBUTING.md`: create dedicated branches, run `./update.sh` for version bumps, and include only the generated artifacts you intend to land. |
| 47 | +- Keep commit subjects short, capitalized, and imperative, mirroring recent history (`Add Node.js v25.0.0`, `chore(deps): bump actions/setup-node from 5.0.0 to 6.0.0`). |
| 48 | +- Use the prompts in `.github/PULL_REQUEST_TEMPLATE.md` to document motivation, testing, and change type; check the appropriate boxes when evidence exists. |
| 49 | +- Reference related issues or downstream PRs when updating `stackbrew.js` or `versions.json`, and attach CI logs or command output that demonstrate the relevant builds/tests succeeded. |
| 50 | + |
| 51 | +## Safety and Permissions |
| 52 | + |
| 53 | +- **Allowed without approval**: read or diff files, edit only the variants you are touching, run targeted Docker builds/tests that do not alter shared configuration, and execute the formatters/tests defined in `.github/workflows/`. |
| 54 | +- **Ask before proceeding**: adding packages to base images, modifying `config`, `versions.json`, `architectures`, introducing new variants or templates, or changing automation scripts such as `update.sh` and `stackbrew.js`. |
| 55 | +- **Never do**: delete supported version directories, force-push to protected branches, publish to Docker Hub manually, or ship unsigned changes to signing key lists. |
| 56 | + |
| 57 | +## Security Notes |
| 58 | + |
| 59 | +- Follow `SECURITY.md`: report Node.js runtime issues through <https://nodejs.org/en/security/>, and route CVEs in base images to the corresponding upstream (Alpine or Debian) before attempting fixes here. |
0 commit comments