Skip to main content

​
Overview

This document explains how collaborators manage the Node.js project. Collaborators should understand the guidelines for new contributors and the project governance model.

​
Who Are Collaborators?

Node.js core collaborators maintain the nodejs/node GitHub repository. The GitHub team for Node.js core collaborators is @nodejs/collaborators. Collaborators have:
  • Commit access to the nodejs/node repository
  • Access to the Node.js continuous integration (CI) jobs

​
Collaborator Activities

  • Helping users and novice contributors
  • Contributing code and documentation changes that improve the project
  • Reviewing and commenting on issues and pull requests
  • Participation in working groups
  • Merging pull requests

​
Issues and Pull Requests

Mind these guidelines, the opinions of other collaborators, and guidance of the TSC. Notify other qualified parties for more input on an issue or a pull request.

​
Welcoming First-Time Contributors

Always show courtesy to individuals submitting issues and pull requests. Be welcoming to first-time contributors, identified by the GitHub First-time contributor badge.
For first-time contributors, check if the commit author is the same as the pull request author. This way, once their pull request lands, GitHub will show them as a Contributor. Ask if they have configured their git username and email to their liking.

​
Closing Issues and Pull Requests

Collaborators can close any issue or pull request that is not relevant to the future of the Node.js project. Where this is unclear, leave the issue or pull request open for several days to allow for discussion.
Remember that issues and pull requests can always be re-opened if necessary.

​
Author Ready Pull Requests

A pull request is author ready when:
  • There is a CI run in progress or completed
  • There is at least one collaborator approval
  • There are no outstanding review comments
Please always add the author ready label to pull requests that qualify. Please always remove it again as soon as the conditions are not met anymore.

​
Handling Own Pull Requests

When you open a pull request, start a CI right away. Later, after new code changes or rebasing, start a new CI. As soon as the pull request is ready to land, please do so. This allows other collaborators to focus on other pull requests.

​
Managing Security Issues

Use the process outlined in SECURITY.md to report security issues. If a user opens a security issue in the public repository:
  1. Ask the user to submit a report through HackerOne
  2. Move the issue to the private premature-disclosures repository
  3. For related pull requests, create an associated issue in the premature-disclosures repository
  4. Open a ticket with GitHub to delete the pull request
  5. Open a new issue in the public repository explaining the deletion
  6. Email [email protected] with links to the issues

​
Accepting Modifications

Contributors propose modifications to Node.js using GitHub pull requests. A pull request must pass code review and CI before landing into the codebase.

​
Code Reviews

At least two collaborators must approve a pull request before the pull request lands. One collaborator approval is enough if the pull request has been open for more than seven days.
Approving a pull request indicates that the collaborator accepts responsibility for the change.
Approval must be from collaborators who are not authors of the change.

​
Special Attention for Dependencies

Ideally pull requests for dependencies should be generated by automation. Pay special attention to pull requests for dependencies which have not been automatically generated and follow the guidance in Maintaining Dependencies.

​
Starting CI

If you are the first collaborator to approve a pull request that has no CI yet, please start one. Please also start a new CI if the pull request creator pushed new code since the last CI run.

​
Consensus Seeking

A pull request can land if it has:
  • The needed approvals
  • Passing CI
  • Required wait time
  • No outstanding objections
Breaking changes must receive TSC review in addition to other requirements.

​
Objections

Collaborators can object to a pull request by using the “Request Changes” GitHub feature.
Dissent comments alone don’t constitute an objection. A blocking objection must be made in the pull request and must include a clear reason.
Requirements for objections:
  • Must be made in the pull request
  • Must include a clear reason
  • Objector must remain responsive for further discussion
  • Should provide actionable steps to resolve the objection
Handling unresponsive objections: If the objector is unresponsive for seven days after a collaborator asks for clarification, a collaborator may dismiss the objection. Escalation to TSC: If reaching consensus is not possible, a collaborator can escalate to the TSC by:
  • Pinging @nodejs/tsc
  • Adding the tsc-agenda label
All Collaborator objections are considered equal. There is no greater weight given to objections from TSC members than from any other Collaborator.

​
Waiting for Approvals

Before landing pull requests, allow 48 hours for input from other collaborators.

​
Fast-Track Eligible Changes

Certain types of pull requests can be fast-tracked and can land after a shorter delay:
  • Focused changes that affect only documentation and/or the test suite
  • code-and-learn tasks
  • good-first-issue pull requests
  • Changes that fix regressions (red CI or broken compilation)
  • Regressions that happen right before a release
Fast-tracking process:
  1. Apply the fast-track label
  2. GitHub Actions workflow adds a comment that collaborators can upvote
  3. If someone disagrees, remove the label
  4. Two collaborators must approve the fast-tracking request
  5. The pull request itself still needs two collaborator approvals and passing CI

​
Testing and CI

All fixes must have a test case which demonstrates the defect. The test should fail before the change, and pass after the change.
Do not land any pull requests without the necessary passing CI runs.
Required CI:
  • GitHub Actions CI: Must be passing (green)
  • Jenkins CI: Required if the pull request contains changes that affect the node binary (green or yellow)

​
Changes That Affect the Node Binary

Changes in the following folders (except comment-only changes) affect the node binary:
  • deps/
  • lib/
  • src/
  • test/
  • tools/code_cache/
  • tools/gyp/
  • tools/icu/
  • tools/inspector-protocol/
  • tools/msvs/
  • tools/snapshot/
  • tools/v8_gypfiles/
Files that touch the build chain:
  • tools/*.py
  • *.gyp
  • *.gypi
  • configure
  • configure.py
  • Makefile
  • vcbuild.bat

​
Useful Jenkins CI Jobs

​
Starting a Jenkins CI Job

  1. Click “Build with Parameters” on the left side
  2. Enter the parameters:
    • GIT_REMOTE_REF: For pull requests use refs/pull/PR_NUMBER/head
    • REBASE_ONTO: Set to origin/main to rebase onto main
  3. Copy the URL and paste it in a pull request comment
The node-test-pull-request CI job can be started by adding the request-ci label to the pull request.

​
Internal vs. Public API

All functionality in the official Node.js documentation is part of the public API. Any undocumented object, property, method, argument, behavior, or event is internal. Internal APIs:
  • All undocumented functionality via process.binding(...)
  • All undocumented functionality in lib/internal/**/*.js
  • Non-exported Symbol properties and methods
  • Any undocumented object property or method that begins with _
  • Any native C/C++ APIs/ABIs requiring the NODE_WANT_INTERNALS flag
Functionality in lib/internal/**/*.js is public if it is re-exported by code in lib/*.js.

​
Breaking Changes

At least two TSC voting members must approve backward-incompatible changes to the main branch. Examples of breaking changes:
  • Removal or redefinition of existing API arguments
  • Changing return values
  • Removing or modifying existing properties on an options argument
  • Adding or removing errors
  • Altering expected timing of an event
  • Changing the side effects of using a particular API

​
Breaking Changes and Deprecations

Existing stable public APIs that change in a backward-incompatible way must undergo deprecation. Exceptions to deprecation requirement:
  • Adding or removing errors thrown or reported by a public API
  • Emitting a runtime warning
  • Changing error messages for errors without error code
  • Altering the timing and non-internal side effects of the public API
  • Changes to errors thrown by dependencies of Node.js, such as V8
  • One-time exceptions granted by the TSC

​
Breaking Changes to Internal Elements

Breaking changes to internal elements can occur in semver-patch or semver-minor commits. Take significant care when making such changes.
Use Canary in the Goldmine (CitGM) to test such changes. If a change will cause ecosystem breakage, then it is semver-major.

​
Unintended Breaking Changes

Sometimes, a change intended to be non-breaking turns out to be breaking. If such a change lands on the main branch:
  • A collaborator can revert it
  • The TSC can apply the semver-major label after-the-fact
If already backported to release lines, open an issue in the TSC repository to discuss how to proceed.

​
Introducing New Modules

Treat commits that introduce new core modules with extra care. Requirements:
  • New modules must only be added with the node: prefix
  • When adding promises to an existing API, add /promises (inspector/promises, etc.)
  • Apply the semver-major label
  • Register a placeholder in npm (if the name is free)
  • Allow at least one week for review
  • Land only after sign-off from at least two TSC voting members
  • Land with a Stability Index of Experimental

​
Deprecations

Node.js uses three Deprecation levels:

​
Documentation-Only Deprecation

  • A deprecation notice appears in the API documentation
  • No functional changes
  • No runtime warnings by default
  • Might cause a runtime warning with the --pending-deprecation flag
  • Apply the notable-change label
  • Not a breaking change (not semver-major)

​
Runtime Deprecation

  • Emits a warning at runtime on first use of the deprecated API
  • Throws a runtime error with the --throw-deprecation flag
  • Breaking change (semver-major)

​
End-of-Life

  • The API is no longer subject to semantic versioning rules
  • Backward-incompatible changes including complete removal can occur at any time
  • Breaking change (semver-major)
Deprecation cycle: A deprecation cycle is a major release during which an API has been in one of the three Deprecation levels.
Documentation-Only Deprecations can land in a minor release. They cannot change to a Runtime Deprecation until the next major release.
No API can change to End-of-Life without going through a Runtime Deprecation cycle.

​
Involving the TSC

Collaborators can opt to elevate pull requests or issues to the TSC if they:
  • Have a significant impact on the codebase
  • Are controversial
  • Are at an impasse among collaborators
To elevate to TSC:
  • @-mention the @nodejs/tsc GitHub team
  • Do not use the GitHub UI to assign to @nodejs/tsc
  • For semver-major PRs, you can request a review from @nodejs/tsc

​
Landing Pull Requests

​
Pre-Landing Checklist

  1. Avoid landing pull requests that have someone else as an assignee
  2. Never use GitHub’s green “Merge pull request” button
  3. Make sure CI is complete and green
  4. Check that the commit message adheres to commit message guidelines
  5. Add all necessary metadata to commit messages
Never use GitHub’s “Merge pull request” button as it adds unnecessary merge commits or loses important metadata.

​
Using the Commit Queue

See the commit queue guide.

​
Using git-node

In most cases, using the git-node command of @node-core/utils is enough to land a pull request. 
npm install -g @node-core/utils
git node land $PRID
To use @node-core/utils, you will need a GitHub access token. If you do not have one, the tool will create one for you the first time you use it.

​
Commit Message Metadata

When landing, add metadata to commit messages:
  • Required: PR-URL: line that references the full GitHub URL of the pull request
  • Optional: Fixes: X line, where X is the full GitHub URL for an issue
  • Optional: Refs: lines referencing a URL for relevant background
  • Required: Reviewed-By: Name <email> line for each collaborator who reviewed the change
Example: 
subsystem: explain the commit in one line

Body of the commit message with more details.

PR-URL: https://github.com/nodejs/node/pull/12345
Fixes: https://github.com/nodejs/node/issues/1337
Refs: https://eslint.org/docs/rules/space-in-parens.html
Reviewed-By: Jane Developer <[email protected]>
Reviewed-By: John Collaborator <[email protected]>

​
Commit Squashing

If a pull request contains more than one commit, it can be landed either by:
  • Squashing into one commit
  • Rebasing all the commits
  • A mix of the two
Generally, a collaborator should land a pull request by squashing. If a pull request has more than one self-contained subsystem commits, a collaborator may land it as several commits.
All commits should be self-contained, meaning every commit should pass all tests. This makes it much easier when bisecting to find a breaking change.

​
Long Term Support

​
What is LTS?

Long Term Support (LTS) guarantees 30-month support cycles for specific Node.js versions. Once a branch enters LTS, the release plan limits the types of changes permitted in the branch. For more information, see the full release plan.

​
How are LTS Branches Managed?

Each LTS release has:
  • A corresponding branch (v10.x, v8.x, etc.)
  • A corresponding staging branch (v10.x-staging, v8.x-staging, etc.)
Commits that land on main are cherry-picked to each staging branch as appropriate.
Only members of @nodejs/backporters should land commits onto LTS staging branches.
  • lts-watch-v?.x: For pull requests to consider for landing in staging branches
  • land-on-v?.x: For pull requests that should land in a future v*.x release
  • backport-requested-v?.x: Indicates that a pull request needs a manual backport
  • backported-to-v?.x: Applied to pull requests for which a backport has been merged
  • dont-land-on-v?.x: For changes that do not apply to a certain release line

​
Who to CC in the Issue Tracker

​
Common Subsystems

SubsystemMaintainers
benchmark/*@nodejs/benchmarking
doc/*, *.md@nodejs/documentation
lib/assert@nodejs/assert
lib/buffer@nodejs/buffer
lib/{crypto,tls,https}@nodejs/crypto
lib/fs, src/{fs,file}@nodejs/fs
lib/{_}http{*}@nodejs/http
lib/{_}stream{*}@nodejs/streams
test/*@nodejs/testing
When things need extra attention, are controversial, or semver-major, CC @nodejs/tsc.
If you cannot find who to cc for a file, git shortlog -n -s <file> can help.

​
Labels

​
General Labels

  • confirmed-bug: Bugs you have verified
  • discuss: Things that need larger discussion
  • fast-track: PRs that need to land faster
  • feature request: Any issue that requests a new feature
  • good first issue: Issues suitable for newcomers to fix
  • meta: Governance, policies, procedures, etc.
  • request-ci: When added to a PR, CI will be started automatically
  • tsc-agenda: Will be added to TSC meeting agenda
  • author-ready: PR is ready to land (has CI, approvals, no outstanding comments)

​
Semver Labels

  • semver-minor: Adds new functionality in a backward-compatible manner
  • semver-major: Breaking changes
Be conservative – that is, if a change has the remote chance of breaking something, go for semver-major. When adding a semver label, add a comment explaining why you’re adding it.

​
Resources