1# Node.js collaborator guide 2 3## Contents 4 5* [Issues and pull requests](#issues-and-pull-requests) 6 * [Welcoming first-time contributors](#welcoming-first-time-contributors) 7 * [Closing issues and pull requests](#closing-issues-and-pull-requests) 8 * [Author ready pull requests](#author-ready-pull-requests) 9 * [Handling own pull requests](#handling-own-pull-requests) 10 * [Security issues](#managing-security-issues) 11* [Accepting modifications](#accepting-modifications) 12 * [Code reviews](#code-reviews) 13 * [Consensus seeking](#consensus-seeking) 14 * [Waiting for approvals](#waiting-for-approvals) 15 * [Testing and CI](#testing-and-ci) 16 * [Useful Jenkins CI jobs](#useful-jenkins-ci-jobs) 17 * [Starting a Jenkins CI job](#starting-a-jenkins-ci-job) 18 * [Internal vs. public API](#internal-vs-public-api) 19 * [Breaking changes](#breaking-changes) 20 * [Breaking changes and deprecations](#breaking-changes-and-deprecations) 21 * [Breaking changes to internal elements](#breaking-changes-to-internal-elements) 22 * [Unintended breaking changes](#unintended-breaking-changes) 23 * [Reverting commits](#reverting-commits) 24 * [Introducing new modules](#introducing-new-modules) 25 * [Additions to Node-API](#additions-to-node-api) 26 * [Deprecations](#deprecations) 27 * [Involving the TSC](#involving-the-tsc) 28* [Landing pull requests](#landing-pull-requests) 29 * [Using the commit queue GitHub labels](#using-the-commit-queue-github-labels) 30 * [Using `git-node`](#using-git-node) 31 * [Technical HOWTO](#technical-howto) 32 * [Troubleshooting](#troubleshooting) 33 * [I made a mistake](#i-made-a-mistake) 34 * [Long Term Support](#long-term-support) 35 * [What is LTS?](#what-is-lts) 36 * [How are LTS branches managed?](#how-are-lts-branches-managed) 37 * [How can I help?](#how-can-i-help) 38* [Who to CC in the issue tracker](#who-to-cc-in-the-issue-tracker) 39 40This document explains how collaborators manage the Node.js project. 41Collaborators should understand the 42[guidelines for new contributors](../../CONTRIBUTING.md) and the 43[project governance model](../../GOVERNANCE.md). 44 45## Issues and pull requests 46 47Mind these guidelines, the opinions of other collaborators, and guidance of the 48[TSC][]. Notify other qualified parties for more input on an issue or a pull 49request. See [Who to CC in the issue tracker](#who-to-cc-in-the-issue-tracker). 50 51### Welcoming first-time contributors 52 53Always show courtesy to individuals submitting issues and pull requests. Be 54welcoming to first-time contributors, identified by the GitHub 55![First-time contributor](../first_timer_badge.png) badge. 56 57For first-time contributors, check if the commit author is the same as the pull 58request author. This way, once their pull request lands, GitHub will show them 59as a _Contributor_. Ask if they have configured their git 60[username][git-username] and [email][git-email] to their liking. 61 62### Closing issues and pull requests 63 64Collaborators can close any issue or pull request that is not relevant to the 65future of the Node.js project. Where this is unclear, leave the issue or pull 66request open for several days to allow for discussion. Where this does not yield 67evidence that the issue or pull request has relevance, close it. Remember that 68issues and pull requests can always be re-opened if necessary. 69 70### Author ready pull requests 71 72A pull request is _author ready_ when: 73 74* There is a CI run in progress or completed. 75* There is at least one collaborator approval. 76* There are no outstanding review comments. 77 78Please always add the `author ready` label to the pull request in that case. 79Please always remove it again as soon as the conditions are not met anymore. 80 81### Handling own pull requests 82 83When you open a pull request, [start a CI](#testing-and-ci) right away. Later, 84after new code changes or rebasing, start a new CI. 85 86As soon as the pull request is ready to land, please do so. This allows other 87collaborators to focus on other pull requests. If your pull request is not ready 88to land but is [author ready](#author-ready-pull-requests), add the 89`author ready` label. If you wish to land the pull request yourself, use the 90"assign yourself" link to self-assign it. 91 92### Managing security issues 93 94Use the process outlined in [SECURITY.md][] to report security 95issues. If a user opens a security issue in the public repository: 96 97* Ask the user to submit a report through HackerOne as outlined in 98 [SECURITY.md][]. 99* Move the issue to the private repository called 100 [premature-disclosures](https://github.com/nodejs/premature-disclosures). 101* For any related pull requests, create an associated issue in the 102 `premature-disclosures` repository. Add a copy of the patch for the 103 pull request to the issue. Add screenshots of discussion from the pull request 104 to the issue. 105* [Open a ticket with GitHub](https://support.github.com/contact) to delete the 106 pull request using Node.js (team) as the account organization. 107* Open a new issue in the public repository with the title `FYI - pull request 108 deleted #YYYY`. Include an explanation for the user: 109 > FYI @xxxx we asked GitHub to delete your pull request while we work on 110 > releases in private. 111* Email `tsc@iojs.org` with links to the issues in the 112 `premature-disclosures` repository. 113 114## Accepting modifications 115 116Contributors propose modifications to Node.js using GitHub pull requests. This 117includes modifications proposed by TSC members and other collaborators. A pull 118request must pass code review and CI before landing into the codebase. 119 120### Code reviews 121 122At least two collaborators must approve a pull request before the pull request 123lands. One collaborator approval is enough if the pull request has been open 124for more than seven days. 125 126Approving a pull request indicates that the collaborator accepts responsibility 127for the change. 128 129Approval must be from collaborators who are not authors of the change. 130 131In some cases, it might be necessary to summon a GitHub team to a pull request 132for review by @-mention. 133See [Who to CC in the issue tracker](#who-to-cc-in-the-issue-tracker). 134 135If you are the first collaborator to approve a pull request that has no CI yet, 136please [start one](#testing-and-ci). Please also start a new CI if the 137pull request creator pushed new code since the last CI run. 138 139### Consensus seeking 140 141A pull request can land if it has the needed [approvals](#code-reviews), 142[CI](#testing-and-ci), [wait time](#waiting-for-approvals) and no 143[outstanding objections](#objections). [Breaking changes](#breaking-changes) 144must receive [TSC review](#involving-the-tsc) in addition to other 145requirements. If a pull request meets all requirements except the 146[wait time](#waiting-for-approvals), please add the 147[`author ready`](#author-ready-pull-requests) label. 148 149#### Objections 150 151Collaborators can object to a pull request by using the "Request 152Changes" GitHub feature. Dissent comments alone don't constitute an 153objection. Any pull request objection must include a clear reason for that 154objection, and the objector must remain responsive for further discussion 155towards consensus about the direction of the pull request. Where possible, 156provide a set of actionable steps alongside the objection. 157 158If the objection is not clear to others, another collaborator can ask an 159objecting collaborator to explain their objection or to provide actionable 160steps to resolve the objection. If the objector is unresponsive for seven 161days after a collaborator asks for clarification, a collaborator may 162dismiss the objection. 163 164Pull requests with outstanding objections must remain open until all 165objections are satisfied. If reaching consensus is not possible, a 166collaborator can escalate the issue to the TSC by pinging `@nodejs/tsc` and 167adding the `tsc-agenda` label to the issue. 168 169#### Helpful resources 170 171* [How to Do Code Reviews Like a Human (Part One)](https://mtlynch.io/human-code-reviews-1/) 172* [How to Do Code Reviews Like a Human (Part Two)](https://mtlynch.io/human-code-reviews-2/) 173* [Code Review Etiquette](https://css-tricks.com/code-review-etiquette/) 174 175### Waiting for approvals 176 177Before landing pull requests, allow 48 hours for input from other collaborators. 178Certain types of pull requests can be fast-tracked and can land after a shorter 179delay. For example: 180 181* Focused changes that affect only documentation and/or the test suite: 182 * `code-and-learn` tasks often fall into this category. 183 * `good-first-issue` pull requests might also be suitable. 184* Changes that fix regressions: 185 * Regressions that break the workflow (red CI or broken compilation). 186 * Regressions that happen right before a release, or reported soon after. 187 188To propose fast-tracking a pull request, apply the `fast-track` label. Then a 189GitHub Actions workflow will add a comment that collaborators can upvote. 190 191If someone disagrees with the fast-tracking request, remove the label. Do not 192fast-track the pull request in that case. 193 194The pull request can be fast-tracked if two collaborators approve the 195fast-tracking request. To land, the pull request itself still needs two 196collaborator approvals and a passing CI. 197 198Collaborators can request fast-tracking of pull requests they did not author. 199In that case only, the request itself is also one fast-track approval. Upvote 200the comment anyway to avoid any doubt. 201 202### Testing and CI 203 204All fixes must have a test case which demonstrates the defect. The test should 205fail before the change, and pass after the change. 206 207Do not land any pull requests without the necessary passing CI runs. 208A passing (green) GitHub Actions CI result is required. A passing (green or 209yellow) [Jenkins CI](https://ci.nodejs.org/) is also required if the pull 210request contains changes that will affect the `node` binary. This is because 211GitHub Actions CI does not cover all the environments supported by Node.js. 212 213<details> 214<summary>Changes that affect the `node` binary</summary> 215 216Changes in the following folders (except comment-only changes) are guaranteed to 217affect the `node` binary: 218 219* `deps/` 220* `lib/` 221* `src/` 222* `test/` 223* `tools/code_cache/` 224* `tools/gyp/` 225* `tools/icu/` 226* `tools/inspector-protocol/` 227* `tools/msvs/` 228* `tools/snapshot/` 229* `tools/v8_gypfiles/` 230 231There are some other files that touch the build chain. Changes in the following 232files also qualify as affecting the `node` binary: 233 234* `tools/*.py` 235* `tools/build-addons.mjs` 236* `*.gyp` 237* `*.gypi` 238* `configure` 239* `configure.py` 240* `Makefile` 241* `vcbuild.bat` 242 243</details> 244 245If there are GitHub Actions CI failures unrelated to the change in the pull 246request, try the " Re-run all jobs" button, on the right-hand side of the 247"Checks" tab. 248 249If there are Jenkins CI failures unrelated to the change in the pull request, 250try "Resume Build". It is in the left navigation of the relevant 251`node-test-pull-request` job. It will preserve all the green results from the 252current job but re-run everything else. Start a fresh CI if more than seven days 253have elapsed since the original failing CI as the compiled binaries for the 254Windows and ARM platforms are only kept for seven days. 255 256If new commits are pushed to the pull request branch after the latest Jenkins 257CI run, a fresh CI run is required. It can be started by pressing "Retry" on 258the left sidebar, or by adding the `request-ci` label to the pull request. 259 260#### Useful Jenkins CI jobs 261 262* [`node-test-pull-request`](https://ci.nodejs.org/job/node-test-pull-request/) 263 is the CI job to test pull requests. It runs the `build-ci` and `test-ci` 264 targets on all supported platforms. 265 266* [`citgm-smoker`](https://ci.nodejs.org/job/citgm-smoker/) 267 uses [`CitGM`](https://github.com/nodejs/citgm) to allow you to run 268 `npm install && npm test` on a large selection of common modules. This is 269 useful to check whether a change will cause breakage in the ecosystem. 270 271* [`node-stress-single-test`](https://ci.nodejs.org/job/node-stress-single-test/) 272 can run a group of tests over and over on a specific platform. Use it to check 273 that the tests are reliable. 274 275* [`node-test-commit-v8-linux`](https://ci.nodejs.org/job/node-test-commit-v8-linux/) 276 runs the standard V8 tests. Run it when updating V8 in Node.js or floating new 277 patches on V8. 278 279* [`node-test-commit-custom-suites-freestyle`](https://ci.nodejs.org/job/node-test-commit-custom-suites-freestyle/) 280 enables customization of test suites and parameters. It can execute test 281 suites not used in other CI test runs (such as tests in the `internet` or 282 `pummel` directories). It can also make sure tests pass when provided with a 283 flag not used in other CI test runs (such as `--worker`). 284 285#### Starting a Jenkins CI job 286 287From the CI Job page, click "Build with Parameters" on the left side. 288 289You generally need to enter only one or both of the following options 290in the form: 291 292* `GIT_REMOTE_REF`: Change to the remote portion of git refspec. 293 To specify the branch this way, `refs/heads/BRANCH` is used 294 (e.g. for `main` -> `refs/heads/main`). 295 For pull requests, it will look like `refs/pull/PR_NUMBER/head` 296 (e.g. for pull request #42 -> `refs/pull/42/head`). 297* `REBASE_ONTO`: Change that to `origin/main` so the pull request gets rebased 298 onto `main`. This can especially be important for pull requests that have been 299 open a while. 300 301Look at the list of jobs on the left hand side under "Build History" and copy 302the link to the one you started (which will be the one on top, but click 303through to make sure it says something like "Started 5 seconds ago" 304(top right) and "Started by user ...". 305 306Copy/paste the URL for the job into a comment in the pull request. 307[`node-test-pull-request`](https://ci.nodejs.org/job/node-test-pull-request/) 308is an exception where the GitHub bot will automatically post for you. 309 310The [`node-test-pull-request`](https://ci.nodejs.org/job/node-test-pull-request/) 311CI job can be started by adding the `request-ci` label into the pull request. 312Once this label is added, `github-actions bot` will start 313the `node-test-pull-request` automatically. If the `github-actions bot` 314is unable to start the job, it will update the label with `request-ci-failed`. 315 316### Internal vs. public API 317 318All functionality in the official Node.js documentation is part of the public 319API. Any undocumented object, property, method, argument, behavior, or event is 320internal. There are exceptions to this rule. Node.js users have come to rely on 321some undocumented behaviors. Collaborators treat many of those undocumented 322behaviors as public. 323 324All undocumented functionality exposed via `process.binding(...)` is internal. 325 326All undocumented functionality in `lib/internal/**/*.js` is internal. It is 327public, though, if it is re-exported by code in `lib/*.js`. 328 329Non-exported `Symbol` properties and methods are internal. 330 331Any undocumented object property or method that begins with `_` is internal. 332 333Any native C/C++ APIs/ABIs requiring the `NODE_WANT_INTERNALS` flag are 334internal. 335 336Sometimes, there is disagreement about whether functionality is internal or 337public. In those cases, the TSC makes a determination. 338 339For undocumented APIs that are public, open a pull request documenting the API. 340 341### Breaking changes 342 343At least two TSC voting members must approve backward-incompatible changes to 344the `main` branch. 345 346Examples of breaking changes include: 347 348* Removal or redefinition of existing API arguments. 349* Changing return values. 350* Removing or modifying existing properties on an options argument. 351* Adding or removing errors. 352* Altering expected timing of an event. 353* Changing the side effects of using a particular API. 354 355#### Breaking changes and deprecations 356 357Existing stable public APIs that change in a backward-incompatible way must 358undergo deprecation. The exceptions to this rule are: 359 360* Adding or removing errors thrown or reported by a public API. 361* Changing error messages for errors without error code. 362* Altering the timing and non-internal side effects of the public API. 363* Changes to errors thrown by dependencies of Node.js, such as V8. 364* One-time exceptions granted by the TSC. 365 366For more information, see [Deprecations](#deprecations). 367 368#### Breaking changes to internal elements 369 370Breaking changes to internal elements can occur in semver-patch or semver-minor 371commits. Take significant care when making and reviewing such changes. Make 372an effort to determine the potential impact of the change in the ecosystem. Use 373[Canary in the Goldmine](https://github.com/nodejs/citgm) to test such changes. 374If a change will cause ecosystem breakage, then it is semver-major. Consider 375providing a Public API in such cases. 376 377#### Unintended breaking changes 378 379Sometimes, a change intended to be non-breaking turns out to be a breaking 380change. If such a change lands on the `main` branch, a collaborator can revert 381it. As an alternative to reverting, the TSC can apply the semver-major label 382after-the-fact. 383 384If the change has already been backported to release lines open 385an issue in the TSC repository to discuss how best to proceed. In the past 386we have often reverted in the release lines and kept the change on main. The 387decision to revert or not most often is based on limiting the impact 388to the ecosystem and how quickly the breaking change is discovered. 389 390If the change is reverted make sure to: 391 392* consider if additional tests can be added to avoid a similar breaking change 393 being missed in the future. 394* consider if adding packages to CITGM would have helped catch 395 the breaking change. 396* ensure the changelog with the revert clearly explains the situation and 397 it's impact on those who may have already used the updated API. 398 399In either case make sure that the documentation and changelog for the 400original breaking change are updated to reflect the breaking behavior. 401 402##### Reverting commits 403 404Revert commits with `git revert <HASH>` or `git revert <FROM>..<TO>`. The 405generated commit message will not have a subsystem and might violate line length 406rules. That is OK. Append the reason for the revert and any `Refs` or `Fixes` 407metadata. Raise a pull request like any other change. 408 409### Introducing new modules 410 411Treat commits that introduce new core modules with extra care. 412 413New modules must only be added with the `node:` prefix. 414 415When adding promises to an existing API, add `/promises` 416(`inspector/promises`, etc.). Apply the `semver-major` label to the addition. 417 418If the new module name is free in npm, register 419a placeholder in the module registry as soon as possible. Link to the pull 420request that introduces the new core module in the placeholder's `README`. 421 422If the module name is not free and the module is 423not widely used, contact the owner to see if they would be willing to transfer 424it to the project. 425 426We register a placeholder without the `node:` prefix whenever 427possible to avoid confusion and typosquatting attacks. 428 429For pull requests introducing new core modules: 430 431* Allow at least one week for review. 432* Land only after sign-off from at least two TSC voting members. 433* Land with a [Stability Index][] of Experimental. The module must remain 434 Experimental until a semver-major release. 435 436### Additions to Node-API 437 438Node-API provides an ABI-stable API guaranteed for future Node.js versions. 439Node-API additions call for unusual care and scrutiny. If a change adds to 440`node_api.h`, `js_native_api.h`, `node_api_types.h`, or `js_native_api_types.h`, 441consult [the relevant guide](https://github.com/nodejs/node/blob/HEAD/doc/contributing/adding-new-napi-api.md). 442 443### Deprecations 444 445Node.js uses three [Deprecation][] levels. For all deprecated APIs, the API 446documentation must state the deprecation status. 447 448* Documentation-Only Deprecation 449 * A deprecation notice appears in the API documentation. 450 * There are no functional changes. 451 * By default, there will be no warnings emitted for such deprecations at 452 runtime. 453 * Might cause a runtime warning with the [`--pending-deprecation`][] flag or 454 `NODE_PENDING_DEPRECATION` environment variable. 455 456* Runtime Deprecation 457 * Emits a warning at runtime on first use of the deprecated API. 458 * If used with the [`--throw-deprecation`][] flag, will throw a runtime error. 459 460* End-of-Life 461 * The API is no longer subject to the semantic versioning rules. 462 * Backward-incompatible changes including complete removal of such APIs can 463 occur at any time. 464 465Apply the `notable-change` label to all pull requests that introduce 466Documentation-Only Deprecations. Such deprecations have no impact on code 467execution. Thus, they are not breaking changes (`semver-major`). 468 469Runtime Deprecations and End-of-Life APIs (internal or public) are breaking 470changes (`semver-major`). The TSC can make exceptions, deciding that one of 471these deprecations is not a breaking change. 472 473Avoid Runtime Deprecations when an alias or a stub/no-op will suffice. An alias 474or stub will have lower maintenance costs for end users and Node.js core. 475 476All deprecations receive a unique and immutable identifier. Documentation, 477warnings, and errors use the identifier when referring to the deprecation. The 478documentation for the deprecation identifier must always remain in the API 479documentation. This is true even if the deprecation is no longer in use (for 480example, due to removal of an End-of-Life deprecated API). 481 482<a id="deprecation-cycle"></a> 483A _deprecation cycle_ is a major release during which an API has been in one of 484the three Deprecation levels. Documentation-Only Deprecations can land in a 485minor release. They can not change to a Runtime Deprecation until the next major 486release. 487 488No API can change to End-of-Life without going through a Runtime Deprecation 489cycle. There is no rule that deprecated code must progress to End-of-Life. 490Documentation-Only and Runtime Deprecations can remain in place for an unlimited 491duration. 492 493Communicate pending deprecations and associated mitigations with the ecosystem 494as soon as possible. If possible, do it before the pull request adding the 495deprecation lands on the `main` branch. 496 497Use the `notable-change` label on pull requests that add or change the 498deprecation level of an API. 499 500### Involving the TSC 501 502Collaborators can opt to elevate pull requests or issues to the [TSC][]. 503Do this if a pull request or issue: 504 505* Is labeled `semver-major`, or 506* Has a significant impact on the codebase, or 507* Is controversial, or 508* Is at an impasse among collaborators who are participating in the discussion. 509 510@-mention the `@nodejs/tsc` GitHub team if you want to elevate an issue to the 511[TSC][]. Do not use the GitHub UI on the right-hand side to assign to 512`@nodejs/tsc` or request a review from `@nodejs/tsc`. 513 514The TSC serves as the final arbiter where required. 515 516## Landing pull requests 517 5181. Avoid landing pull requests that have someone else as an assignee. Authors 519 who wish to land their own pull requests will self-assign them. Sometimes, an 520 author will delegate to someone else. If in doubt, ask the assignee whether 521 it is okay to land. 5222. Never use GitHub's green ["Merge pull request"][] button. Reasons for not 523 using the web interface button: 524 * The "Create a merge commit" method will add an unnecessary merge commit. 525 * The "Squash and merge" method will add metadata (the pull request #) to the 526 commit title. If more than one author contributes to the pull request, 527 squashing only keeps one author. 528 * The "Rebase and merge" method has no way of adding metadata to the commit. 5293. Make sure CI is complete and green. If the CI is not green, check for 530 unreliable tests and infrastructure failures. If there are no corresponding 531 issues in the [node][unreliable tests] or 532 [build](https://github.com/nodejs/build/issues) repositories, open new 533 issues. Run a new CI any time someone pushes new code to the pull request. 5344. Check that the commit message adheres to [commit message guidelines][]. 5355. Add all necessary [metadata](#metadata) to commit messages before landing. If 536 you are unsure exactly how to format the commit messages, use the commit log 537 as a reference. See [this commit][commit-example] as an example. 538 539For pull requests from first-time contributors, be 540[welcoming](#welcoming-first-time-contributors). Also, verify that their git 541settings are to their liking. 542 543If a pull request contains more than one commit, it can be landed either by 544squashing into one commit or by rebasing all the commits, or a mix of the two. 545Generally, a collaborator should land a pull request by squashing. If a pull 546request has more than one self-contained subsystem commits, a collaborator 547may land it as several commits. 548 549All commits should be self-contained, meaning every commit should pass all 550tests. This makes it much easier when bisecting to find a breaking change. 551 552### Using the commit queue GitHub labels 553 554See the [commit queue guide][commit-queue.md]. 555 556### Using `git-node` 557 558In most cases, using [the `git-node` command][git-node] of [`node-core-utils`][] 559is enough to land a pull request. If you discover a problem when using 560this tool, please file an issue [to the issue tracker][node-core-utils-issues]. 561 562Quick example: 563 564```text 565$ npm install -g node-core-utils 566$ git node land $PRID 567``` 568 569To use `node-core-utils`, you will need a GitHub access token. If you do not 570have one, `node-core-utils` will create one for you the first time you use it. 571To do this, it will ask for your GitHub password and two-factor authentication 572code. If you wish to create the token yourself in advance, see 573[the `node-core-utils` guide][node-core-utils-credentials]. 574 575### Technical HOWTO 576 577Infrequently, it is necessary to manually perform the steps required to land a 578pull request rather than rely on `git-node`. 579 580<details> 581<Summary>Manual Landing Steps</Summary> 582 583Clear any `am`/`rebase` that might already be underway: 584 585```text 586$ git am --abort 587$ git rebase --abort 588``` 589 590Checkout proper target branch: 591 592```text 593$ git checkout main 594``` 595 596Update the tree (assumes your repository is set up as detailed in 597[CONTRIBUTING.md](./pull-requests.md#step-1-fork)): 598 599```text 600$ git fetch upstream 601$ git merge --ff-only upstream/main 602``` 603 604Apply external patches: 605 606```text 607$ curl -L https://github.com/nodejs/node/pull/xxx.patch | git am --whitespace=fix 608``` 609 610If the merge fails even though recent CI runs were successful, try a 3-way 611merge: 612 613```text 614$ git am --abort 615$ curl -L https://github.com/nodejs/node/pull/xxx.patch | git am -3 --whitespace=fix 616``` 617 618If the 3-way merge succeeds, check the results against the original pull 619request. Build and test on at least one platform before landing. 620 621If the 3-way merge fails, then it is most likely that a conflicting pull request 622has landed since the CI run. You will have to ask the author to rebase. 623 624Check and re-review the changes: 625 626```text 627$ git diff upstream/main 628``` 629 630Check the number of commits and commit messages: 631 632```text 633$ git log upstream/main...main 634``` 635 636Squash commits and add metadata: 637 638```text 639$ git rebase -i upstream/main 640``` 641 642This will open a screen like this (in the default shell editor): 643 644```text 645pick 6928fc1 crypto: add feature A 646pick 8120c4c add test for feature A 647pick 51759dc crypto: feature B 648pick 7d6f433 test for feature B 649 650# Rebase f9456a2..7d6f433 onto f9456a2 651# 652# Commands: 653# p, pick = use commit 654# r, reword = use commit, but edit the commit message 655# e, edit = use commit, but stop for amending 656# s, squash = use commit, but meld into previous commit 657# f, fixup = like "squash", but discard this commit's log message 658# x, exec = run command (the rest of the line) using shell 659# 660# These lines can be re-ordered; they are executed from top to bottom. 661# 662# If you remove a line here THAT COMMIT WILL BE LOST. 663# 664# However, if you remove everything, the rebase will be aborted. 665# 666# Note that empty commits are commented out 667``` 668 669Replace a couple of `pick`s with `fixup` to squash them into a 670previous commit: 671 672```text 673pick 6928fc1 crypto: add feature A 674fixup 8120c4c add test for feature A 675pick 51759dc crypto: feature B 676fixup 7d6f433 test for feature B 677``` 678 679Replace `pick` with `reword` to change the commit message: 680 681```text 682reword 6928fc1 crypto: add feature A 683fixup 8120c4c add test for feature A 684reword 51759dc crypto: feature B 685fixup 7d6f433 test for feature B 686``` 687 688Save the file and close the editor. When prompted, enter a new commit message 689for that commit. This is an opportunity to fix commit messages. 690 691* The commit message text must conform to the [commit message guidelines][]. 692* <a name="metadata"></a>Change the original commit message to include metadata. (The 693 [`git node metadata`][git-node-metadata] command can generate the metadata 694 for you). 695 696 * Required: A `PR-URL:` line that references the full GitHub URL of the pull 697 request. This makes it easy to trace a commit back to the conversation that 698 led up to that change. 699 * Optional: A `Fixes: X` line, where _X_ is the full GitHub URL for an 700 issue. A commit message can include more than one `Fixes:` lines. 701 * Optional: One or more `Refs:` lines referencing a URL for any relevant 702 background. 703 * Required: A `Reviewed-By: Name <email>` line for each collaborator who 704 reviewed the change. 705 * Useful for @mentions / contact list if something goes wrong in the 706 pull request. 707 * Protects against the assumption that GitHub will be around forever. 708 709Other changes might have landed on `main` since the successful CI run. As a 710precaution, run tests (`make -j4 test` or `vcbuild test`). 711 712Confirm that the commit message format is correct using 713[core-validate-commit](https://github.com/nodejs/core-validate-commit). 714 715```text 716$ git rev-list upstream/main...HEAD | xargs core-validate-commit 717``` 718 719Optional: For your own commits, force push the amended commit to the pull 720request branch. If your branch name is `bugfix`, then: 721`git push --force-with-lease origin main:bugfix`. Don't close the pull 722request. It will close after you push it upstream. It will have the purple 723merged status rather than the red closed status. If you close the pull request 724before GitHub adjusts its status, it will show up as a 0 commit pull 725request with no changed files. The order of operations is important. 726If you push upstream before you push to your branch, GitHub will close 727the issue with the red closed status. 728 729Time to push it: 730 731```text 732$ git push upstream main 733``` 734 735Close the pull request with a "Landed in `<commit hash>`" comment. Even if 736your pull request shows the purple merged status, 737add the "Landed in \<commit hash>..\<commit hash>" comment if you added 738more than one commit. 739 740</details> 741 742### Troubleshooting 743 744Sometimes, when running `git push upstream main`, you might get an error 745message like this: 746 747```console 748To https://github.com/nodejs/node 749 ! [rejected] main -> main (fetch first) 750error: failed to push some refs to 'https://github.com/nodejs/node' 751hint: Updates were rejected because the tip of your current branch is behind 752hint: its remote counterpart. Integrate the remote changes (e.g. 753hint: 'git pull ...') before pushing again. 754hint: See the 'Note about fast-forwards' in 'git push --help' for details. 755``` 756 757That means a commit has landed since your last rebase against `upstream/main`. 758To fix this, pull with rebase from upstream, run the tests again, and (if the 759tests pass) push again: 760 761```bash 762git pull upstream main --rebase 763make -j4 test 764git push upstream main 765``` 766 767### I made a mistake 768 769* Ping a TSC voting member. 770* With `git`, there's a way to override remote trees by force pushing 771 (`git push -f`). This is generally forbidden as it creates conflicts in other 772 people's forks. It is permissible for simpler slip-ups such as typos in commit 773 messages. You are only allowed to force push to any Node.js branch within 10 774 minutes from your original push. If someone else pushes to the branch or the 775 10-minute period passes, consider the commit final. 776 * Use `--force-with-lease` to reduce the chance of overwriting someone else's 777 change. 778 779### Long Term Support 780 781#### What is LTS? 782 783Long Term Support (LTS) guarantees 30-month support cycles for specific Node.js 784versions. You can find more information 785[in the full release plan](https://github.com/nodejs/Release#release-plan). Once 786a branch enters LTS, the release plan limits the types of changes permitted in 787the branch. 788 789#### How are LTS branches managed? 790 791Each LTS release has a corresponding branch (v10.x, v8.x, etc.). Each also has a 792corresponding staging branch (v10.x-staging, v8.x-staging, etc.). 793 794Commits that land on `main` are cherry-picked to each staging branch as 795appropriate. If a change applies only to the LTS branch, open the pull request 796against the _staging_ branch. Commits from the staging branch land on the LTS 797branch only when a release is being prepared. They might land on the LTS branch 798in a different order than they do in staging. 799 800Only members of @nodejs/backporters should land commits onto LTS staging 801branches. 802 803#### How can I help? 804 805When you send your pull request, please state if your change is breaking. Also 806state if you think your patch is a good candidate for backporting. For more 807information on backporting, please see the [backporting guide][]. 808 809There are several LTS-related labels: 810 811* `lts-watch-` labels are for pull requests to consider for landing in staging 812 branches. For example, `lts-watch-v10.x` would be for a change 813 to consider for the `v10.x-staging` branch. 814 815* `land-on-` are for pull requests that should land in a future v\*.x 816 release. For example, `land-on-v10.x` would be for a change to land in Node.js 817 10.x. 818 819Any collaborator can attach these labels to any pull request/issue. As commits 820land on the staging branches, the backporter removes the `lts-watch-` label. 821Likewise, as commits land in an LTS release, the releaser removes the `land-on-` 822label. 823 824Attach the appropriate `lts-watch-` label to any pull request that 825might impact an LTS release. 826 827## Who to CC in the issue tracker 828 829| Subsystem | Maintainers | 830| -------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | 831| `benchmark/*` | @nodejs/benchmarking, @mscdex | 832| `doc/*`, `*.md` | @nodejs/documentation | 833| `lib/assert` | @nodejs/assert | 834| `lib/async_hooks` | @nodejs/async\_hooks for bugs/reviews (+ @nodejs/diagnostics for API) | 835| `lib/buffer` | @nodejs/buffer | 836| `lib/child_process` | @nodejs/child\_process | 837| `lib/cluster` | @nodejs/cluster | 838| `lib/{crypto,tls,https}` | @nodejs/crypto | 839| `lib/dgram` | @nodejs/dgram | 840| `lib/domains` | @nodejs/domains | 841| `lib/fs`, `src/{fs,file}` | @nodejs/fs | 842| `lib/{_}http{*}` | @nodejs/http | 843| `lib/inspector.js`, `src/inspector_*` | @nodejs/v8-inspector | 844| `lib/internal/bootstrap/*` | @nodejs/process | 845| `lib/internal/url`, `src/node_url` | @nodejs/url | 846| `lib/net` | @bnoordhuis, @indutny, @nodejs/streams | 847| `lib/repl` | @nodejs/repl | 848| `lib/{_}stream{*}` | @nodejs/streams | 849| `lib/timers` | @nodejs/timers | 850| `lib/util` | @nodejs/util | 851| `lib/zlib` | @nodejs/zlib | 852| `src/async_wrap.*` | @nodejs/async\_hooks | 853| `src/node_api.*` | @nodejs/node-api | 854| `src/node_crypto.*`, `src/crypto` | @nodejs/crypto | 855| `test/*` | @nodejs/testing | 856| `tools/node_modules/eslint`, `.eslintrc` | @nodejs/linting | 857| build | @nodejs/build | 858| `src/module_wrap.*`, `lib/internal/modules/*`, `lib/internal/vm/module.js` | @nodejs/modules | 859| GYP | @nodejs/gyp | 860| performance | @nodejs/performance | 861| platform specific | @nodejs/platform-{aix,arm,freebsd,macos,ppc,smartos,s390,windows,windows-arm} | 862| python code | @nodejs/python | 863| upgrading c-ares | @rvagg | 864| upgrading http-parser | @nodejs/http, @nodejs/http2 | 865| upgrading libuv | @nodejs/libuv | 866| upgrading npm | @nodejs/npm | 867| upgrading V8 | @nodejs/V8, @nodejs/post-mortem | 868| Embedded use or delivery of Node.js | @nodejs/delivery-channels | 869 870When things need extra attention, are controversial, or `semver-major`: 871@nodejs/tsc 872 873If you cannot find who to cc for a file, `git shortlog -n -s <file>` can help. 874 875## Labels 876 877### General labels 878 879* `confirmed-bug`: Bugs you have verified 880* `discuss`: Things that need larger discussion 881* `feature request`: Any issue that requests a new feature 882* `good first issue`: Issues suitable for newcomers to fix 883* `meta`: Governance, policies, procedures, etc. 884* `tsc-agenda`: Open issues and pull requests with this label will be added to 885 the Technical Steering Committee meeting agenda 886 887*** 888 889* `author-ready` - A pull request is _author ready_ when: 890 * There is a CI run in progress or completed. 891 * There is at least one collaborator approval (or two TSC approvals for 892 semver-major pull requests). 893 * There are no outstanding review comments. 894 895Please always add the `author ready` label to pull requests that qualify. 896Please always remove it again as soon as the conditions are not met anymore, 897such as if the CI run fails or a new outstanding review comment is posted. 898 899*** 900 901* `semver-{minor,major}` 902 * be conservative – that is, if a change has the remote _chance_ of breaking 903 something, go for semver-major 904 * when adding a semver label, add a comment explaining why you're adding it 905 * minor vs. patch: roughly: "does it add a new method / does it add a new 906 section to the docs" 907 * major vs. everything else: run last versions tests against this version, if 908 they pass, **probably** minor or patch 909 910### LTS/version labels 911 912We use labels to keep track of which branches a commit should land on: 913 914* `dont-land-on-v?.x` 915 * For changes that do not apply to a certain release line 916 * Also used when the work of backporting a change outweighs the benefits 917* `land-on-v?.x` 918 * Used by releasers to mark a pull request as scheduled for inclusion in an 919 LTS release 920 * Applied to the original pull request for clean cherry-picks, to the backport 921 pull request otherwise 922* `backport-requested-v?.x` 923 * Used to indicate that a pull request needs a manual backport to a branch in 924 order to land the changes on that branch 925 * Typically applied by a releaser when the pull request does not apply cleanly 926 or it breaks the tests after applying 927 * Will be replaced by either `dont-land-on-v?.x` or `backported-to-v?.x` 928* `backported-to-v?.x` 929 * Applied to pull requests for which a backport pull request has been merged 930* `lts-watch-v?.x` 931 * Applied to pull requests which the Release working group should consider 932 including in an LTS release 933 * Does not indicate that any specific action will be taken, but can be 934 effective as messaging to non-collaborators 935* `release-agenda` 936 * For things that need discussion by the Release working group 937 * (for example semver-minor changes that need or should go into an LTS 938 release) 939* `v?.x` 940 * Automatically applied to changes that do not target `main` but rather the 941 `v?.x-staging` branch 942 943Once a release line enters maintenance mode, the corresponding labels do not 944need to be attached anymore, as only important bugfixes will be included. 945 946### Other labels 947 948* Operating system labels 949 * `macos`, `windows`, `smartos`, `aix` 950 * No `linux` label because it is the implied default 951* Architecture labels 952 * `arm`, `mips`, `s390`, `ppc` 953 * No `x86{_64}` label because it is the implied default 954 955["Merge pull request"]: https://help.github.com/articles/merging-a-pull-request/#merging-a-pull-request-on-github 956[Deprecation]: https://en.wikipedia.org/wiki/Deprecation 957[SECURITY.md]: https://github.com/nodejs/node/blob/HEAD/SECURITY.md 958[Stability Index]: ../api/documentation.md#stability-index 959[TSC]: https://github.com/nodejs/TSC 960[`--pending-deprecation`]: ../api/cli.md#--pending-deprecation 961[`--throw-deprecation`]: ../api/cli.md#--throw-deprecation 962[`node-core-utils`]: https://github.com/nodejs/node-core-utils 963[backporting guide]: backporting-to-release-lines.md 964[commit message guidelines]: pull-requests.md#commit-message-guidelines 965[commit-example]: https://github.com/nodejs/node/commit/b636ba8186 966[commit-queue.md]: ./commit-queue.md 967[git-email]: https://help.github.com/articles/setting-your-commit-email-address-in-git/ 968[git-node]: https://github.com/nodejs/node-core-utils/blob/HEAD/docs/git-node.md 969[git-node-metadata]: https://github.com/nodejs/node-core-utils/blob/HEAD/docs/git-node.md#git-node-metadata 970[git-username]: https://help.github.com/articles/setting-your-username-in-git/ 971[node-core-utils-credentials]: https://github.com/nodejs/node-core-utils#setting-up-credentials 972[node-core-utils-issues]: https://github.com/nodejs/node-core-utils/issues 973[unreliable tests]: https://github.com/nodejs/node/issues?q=is%3Aopen+is%3Aissue+label%3A%22CI+%2F+flaky+test%22 974