|
| 1 | +# Large pull requests |
| 2 | + |
| 3 | +* [Overview](#overview) |
| 4 | +* [What qualifies as a large pull request](#what-qualifies-as-a-large-pull-request) |
| 5 | +* [Who can open a large pull request](#who-can-open-a-large-pull-request) |
| 6 | +* [Requirements](#requirements) |
| 7 | + * [Detailed pull request description](#detailed-pull-request-description) |
| 8 | + * [Review guide](#review-guide) |
| 9 | + * [Approval requirements](#approval-requirements) |
| 10 | + * [Dependency changes](#dependency-changes) |
| 11 | +* [Splitting large pull requests](#splitting-large-pull-requests) |
| 12 | + * [Feature forks and branches](#feature-forks-and-branches) |
| 13 | +* [Guidance for reviewers](#guidance-for-reviewers) |
| 14 | + |
| 15 | +## Overview |
| 16 | + |
| 17 | +Large pull requests are difficult to review thoroughly. They are likely to sit |
| 18 | +for a long time without receiving adequate review, and when they do get reviewed, |
| 19 | +the quality of that review is often lower due to reviewer fatigue. Contributors |
| 20 | +should avoid creating large pull requests except in those cases where it is |
| 21 | +effectively unavoidable, such as when adding a major new subsystem. |
| 22 | + |
| 23 | +This document outlines the policy for authoring and reviewing large pull |
| 24 | +requests in the Node.js project. |
| 25 | + |
| 26 | +## What qualifies as a large pull request |
| 27 | + |
| 28 | +A pull request is considered large when it exceeds **3000 lines** of net |
| 29 | +change (lines added minus lines deleted). This threshold applies across all |
| 30 | +files in the pull request, including changes in `deps/`, `test/`, `doc/`, |
| 31 | +`lib/`, `src/`, and `tools/`. |
| 32 | + |
| 33 | +Changes in `deps/` are included in this count. Dependency changes are |
| 34 | +sensitive because they often receive less scrutiny than first-party code. |
| 35 | + |
| 36 | +The following categories of pull requests are **excluded** from this policy, |
| 37 | +even if they exceed the line threshold: |
| 38 | + |
| 39 | +* Routine dependency updates (e.g., V8, ICU, undici, uvwasi) generated by |
| 40 | + automation or performed by collaborators following the standard dependency |
| 41 | + update process. |
| 42 | +* Web Platform Tests (WPT) imports and updates. |
| 43 | +* Other bot-issued or automated pull requests (e.g., license updates, test |
| 44 | + fixture regeneration). |
| 45 | + |
| 46 | +These pull requests already have established review processes and do not |
| 47 | +benefit from the additional requirements described here. |
| 48 | + |
| 49 | +## Who can open a large pull request |
| 50 | + |
| 51 | +Large pull requests may only be opened by existing |
| 52 | +[collaborators](https://github.com/nodejs/node/#current-project-team-members). |
| 53 | +Non-collaborators are strongly discouraged from opening pull requests of this |
| 54 | +size. Collaborators should close large pull requests from non-collaborators and |
| 55 | +direct the author to discuss the proposed changes in an issue first, and to |
| 56 | +find a collaborator to champion the work. |
| 57 | + |
| 58 | +## Requirements |
| 59 | + |
| 60 | +All large pull requests must satisfy the following requirements in addition to |
| 61 | +the standard [pull request requirements](./pull-requests.md). |
| 62 | + |
| 63 | +### Detailed pull request description |
| 64 | + |
| 65 | +The pull request description must provide sufficient context for reviewers |
| 66 | +to understand the change. The description should explain: |
| 67 | + |
| 68 | +* The motivation for the change. |
| 69 | +* The high-level approach and architecture. |
| 70 | +* Any alternatives that were considered and why they were rejected. |
| 71 | +* How the change interacts with existing subsystems. |
| 72 | + |
| 73 | +A thorough pull request description is sufficient. There is no requirement |
| 74 | +to produce a separate design document, although contributors may choose to |
| 75 | +link to a GitHub issue or other discussion where the design was developed. |
| 76 | + |
| 77 | +### Review guide |
| 78 | + |
| 79 | +The pull request description must include a review guide that helps reviewers |
| 80 | +navigate the change. The review guide should: |
| 81 | + |
| 82 | +* Identify the key files and directories to review. |
| 83 | +* Describe the order in which files should be reviewed. |
| 84 | +* Highlight the most critical sections that need careful attention. |
| 85 | +* Include a testing plan explaining how the change has been validated and |
| 86 | + how reviewers can verify the behavior. |
| 87 | + |
| 88 | +### Approval requirements |
| 89 | + |
| 90 | +Large pull requests follow the same approval path as semver-major changes: |
| 91 | + |
| 92 | +* At least **two TSC member approvals** are required. |
| 93 | +* The standard 48-hour wait time applies. Given the complexity of large pull |
| 94 | + requests, authors should expect and allow for a longer review period. |
| 95 | +* CI must pass before landing. |
| 96 | + |
| 97 | +### Dependency changes |
| 98 | + |
| 99 | +When a large pull request adds or modifies a dependency in `deps/`: |
| 100 | + |
| 101 | +* Dependency changes should be in a **separate commit** from the rest of the |
| 102 | + pull request. This makes it easier to review the dependency update |
| 103 | + independently from the first-party code changes. When the pull request is |
| 104 | + squashed on landing, the dependency commit should be the one that carries |
| 105 | + the squashed commit message, so that `git log` clearly reflects the |
| 106 | + overall change. |
| 107 | +* The provenance and integrity of the dependency must be verifiable. |
| 108 | + Include documentation of how the dependency was obtained and how |
| 109 | + reviewers can reproduce the build artifact. |
| 110 | + |
| 111 | +## Splitting large pull requests |
| 112 | + |
| 113 | +Contributors should always consider whether a large pull request can be split |
| 114 | +into smaller, independently reviewable pieces. Strategies include: |
| 115 | + |
| 116 | +* Landing foundational internal APIs first, then building on top of them. |
| 117 | +* Landing refactoring or preparatory changes before the main feature. |
| 118 | + |
| 119 | +Each pull request in a split series should remain self-contained: it should |
| 120 | +include the implementation, tests, and documentation needed for that piece |
| 121 | +to stand on its own. |
| 122 | + |
| 123 | +### Feature forks and branches |
| 124 | + |
| 125 | +For extremely large or complex changes that develop over time, such as adding |
| 126 | +a major new subsystem, contributors should consider using a feature fork. |
| 127 | +This approach has been used successfully in the past for subsystems like QUIC. |
| 128 | + |
| 129 | +The feature fork must be hosted in a **separate GitHub repository**, managed |
| 130 | +by the collaborator championing the change. The repository can live in the |
| 131 | +[nodejs organization](https://github.com/nodejs) or be a personal repository |
| 132 | +of the champion. The champion is responsible for coordinating development, |
| 133 | +managing access, and ensuring the fork stays up to date with `main`. |
| 134 | + |
| 135 | +A feature fork allows: |
| 136 | + |
| 137 | +* Incremental development with multiple collaborators. |
| 138 | +* Review of individual commits rather than one monolithic diff. |
| 139 | +* CI validation at each stage of development. |
| 140 | +* Independent issue tracking and discussion in the fork repository. |
| 141 | + |
| 142 | +When the work is ready, the final merge into `main` via a pull request still |
| 143 | +requires the same approval and review requirements as any other large pull |
| 144 | +request. |
| 145 | + |
| 146 | +## Guidance for reviewers |
| 147 | + |
| 148 | +Reviewing a large pull request is a significant time investment. Reviewers |
| 149 | +should: |
| 150 | + |
| 151 | +* Read the pull request description and review guide before diving into the |
| 152 | + code. |
| 153 | +* Focus review effort on `lib/` and `src/` changes, which have the highest |
| 154 | + impact on the runtime. `test/` and `doc/` changes, while important, are |
| 155 | + lower risk. |
| 156 | +* Not hesitate to request that the author split the pull request if it can |
| 157 | + reasonably be broken into smaller pieces. |
| 158 | +* Coordinate with other reviewers to divide the review workload when possible. |
0 commit comments