Development workflow

A condensed walkthrough of the contributor loop. The exhaustive version is at doc/contributing/pull-requests.md.

1. Fork and clone

git clone git@github.com:<you>/node.git
cd node
git remote add upstream https://github.com/nodejs/node.git
git fetch upstream

Keep your main in sync with upstream/main. Topic branches go off upstream/main.

2. Branch

git checkout -b <subsystem>-<short-summary>

The branch name is informal; only the commit subject is enforced. Subsystem names are the ones in the Appendix: subsystems of the contributing doc.

3. Code

Follow Patterns and conventions:

• Use primordials in lib/internal/**.
• Validate with internal/validators.js.
• Throw internal/errors.js codes.
• Keep lib/internal/bootstrap/** snapshot-friendly.
• Format C++ with clang-format.

If you change deps/**, you usually need a counterpart upstream PR — most deps/ directories are vendored. The exceptions and update procedures are in doc/contributing/maintaining/.

4. Test locally

make -j"$(nproc)"
python3 tools/test.py test/parallel/test-<related>-*.js
make lint

For C++ changes, run make cctest. For doc changes, run make doc lint-md.

The full categories are described in Testing.

5. Commit

The commit subject format is <subsystem>: short imperative summary, lowercase, ≤ 50 characters. Examples from git log:

url: process crash via malformed UNC hostname in pathToFileURL()
build: add rust target for macOS cross compiles
http2: expose writable stream state on compat response
src: add missing <cstdlib> for abort() declaration
doc: correct diagnostics_channel built-in channel names

The body wraps at 72. Reference fixed issues with Fixes: and related ones with Refs:. Always sign off with Signed-off-by: Your Name <you@example.com> (git commit -s).

PR-URL: and Reviewed-By: lines are added at land time by the merger; you do not write them yourself.

A commit-message lint runs on every PR (.github/workflows/commit-lint.yml).

6. Rebase, never merge

git fetch upstream
git rebase upstream/main

Squash review fixups into the original commit if possible. The Collaborator landing the PR may further squash via git node land.

7. Push and open the PR

git push -u origin <branch>

Open the PR against nodejs/node:main. The PR template asks for:

• Description of the change.
• Fixes / Refs links.
• Whether you ran the relevant subset of tests.

GitHub Actions will run linters, commit-lint, and a smoke build immediately. A Collaborator will trigger the full Jenkins CI by commenting @nodejs-github-bot run CI (or attaching the request-ci label).

8. Address review feedback

• Respect the minimum wait time (48h, 72h on weekends).
• Don't force-push aggressively; reviewers want stable diffs.
• When CI fails, look at the Jenkins job (link will be posted by the bot). Common failures: flaky tests on Windows, ICU mismatches, ASan use-after-free.

9. Land

Once you have two Collaborator approvals and CI is green, a Collaborator runs git node land <PR-URL> which:

1. Fetches your PR.
2. Rewrites each commit subject with metadata (PR-URL, Reviewed-By, Refs).
3. Runs make lint and a basic test smoke.
4. Pushes to main.

External contributors do not have the push rights for this; you wait for a Collaborator to drive it.

Continuous-integration tooling

• nodejs-github-bot posts CI links and reflects status.
• commit-queue label triggers .github/workflows/commit-queue.yml, which auto-lands when criteria are met (active for select Collaborators).
• request-ci label triggers .github/workflows/auto-start-ci.yml to kick the full Jenkins run.
• The commit-lint-problem-matcher.json and remark-lint-problem-matcher.json files map lint failures into GitHub annotations.

For the full landing workflow used by Collaborators, including how to handle backports and security releases, read doc/contributing/collaborator-guide.md and doc/contributing/security-release-process.md.