CONTRIBUTING.md

Contributing

Use Node.js 22+ and npm. Create development branches from prerelease and open feature/fix pull requests targeting prerelease. Only the repository's prerelease branch may open a release PR targeting main.

CI enforces development version >= prerelease and the resulting prerelease version > main. Release PRs require prerelease version > main. Source versions must be stable X.Y.Z values and match package-lock.json; beta suffixes are added only during publishing. After a stable release, bump the target version in the next development PR, for example:

npm version 0.1.1 --workspace @hyper3d/cli --no-git-tag-version

PRs run CI once; pushing a development branch without a PR does not trigger CI. Use a draft PR for early checks. New PR commits cancel obsolete checks. Merge commits when promoting prerelease to main preserve the shared branch history.

npm ci
npm run cli -- --help
npm run format
npm run lint
npm run typecheck
npm test
npm run test:install

The CLI source is in packages/cli/src, written in strict TypeScript and compiled to packages/cli/dist. Tests exercise the compiled JavaScript. The build copies contract JSON into the artifact; consumers do not need TypeScript or install scripts. Do not commit dist.

ESLint and Prettier enforce 80-column formatting, single quotes, trailing commas, sorted import groups, unused-import checks and type-aware promise rules. npm run lint:fix fixes lint issues; npm run format:check checks formatting without changing files. Tests and maintenance scripts are linted as JavaScript.

Development PRs check formatting and lint once on Linux. The full Linux, macOS and Windows matrix with Node.js 22 and 24 compiles with TypeScript, runs unit/integration tests, and checks actual packed installations. Compilation already checks types, so CI does not also run the standalone typecheck command. Tests use local servers and fixtures; no production credentials or billable operations are needed.

Promotion PRs and main releases reuse successful prerelease verification only when their entire Git tree matches that verified commit. Otherwise they run full CI. Release policy and publication installation checks remain required. Changes to CI itself follow the same development -> prerelease -> main PR flow.

npm run test:install packs the CLI, installs it into temporary global and local prefixes, and exercises its executable and one-off npm execution. It also verifies pnpm 10 and Yarn Classic installations. It downloads normal npm dependencies and removes its temporary installations afterward.

For integration details, see architecture.md. For publishing and repository protection, see releasing.md.

Add the skip-release label to a PR before merging to skip its automatic npm publication and GitHub Release. CI still runs. The label applies only to that merge, so a later prerelease -> main PR may still publish normally.