doc: address review feedback on large pull requests guide

- Exclude routine dependency/WPT/bot PRs from the policy
- Replace design document requirement with detailed PR description
- Clarify dependency commit ordering for squash landing
- Remove splitting strategies that contradict self-contained PRs
- Add links from CONTRIBUTING.md, pull-requests.md,
  collaborator-guide.md

Signed-off-by: Matteo Collina <matteo.collina@gmail.com>

Author: mcollina

CONTRIBUTING.md

@@ -45,6 +45,7 @@ dependencies, and tools contained in the `nodejs/node` repository.
 * [Setting up your local environment](./doc/contributing/pull-requests.md#setting-up-your-local-environment)
 * [The Process of Making Changes](./doc/contributing/pull-requests.md#the-process-of-making-changes)
 * [Reviewing Pull Requests](./doc/contributing/pull-requests.md#reviewing-pull-requests)
+* [Large Pull Requests](./doc/contributing/large-pull-requests.md)
 * [Notes](./doc/contributing/pull-requests.md#notes)
 
 ## Developer's Certificate of Origin 1.1

doc/contributing/collaborator-guide.md

@@ -132,6 +132,9 @@ Pay special attention to pull requests for dependencies which have not
 been automatically generated and follow the guidance in
 [Maintaining Dependencies](https://github.com/nodejs/node/blob/main/doc/contributing/maintaining/maintaining-dependencies.md#updating-dependencies).
 
+Pull requests that exceed 3000 lines of changes have additional requirements.
+See the [large pull requests][] guide.
+
 In some cases, it might be necessary to summon a GitHub team to a pull request
 for review by @-mention.
 See [Who to CC in the issue tracker](#who-to-cc-in-the-issue-tracker).
@@ -1068,6 +1071,7 @@ need to be attached anymore, as only important bugfixes will be included.
 [git-node]: https://github.com/nodejs/node-core-utils/blob/HEAD/docs/git-node.md
 [git-node-metadata]: https://github.com/nodejs/node-core-utils/blob/HEAD/docs/git-node.md#git-node-metadata
 [git-username]: https://help.github.com/articles/setting-your-username-in-git/
+[large pull requests]: large-pull-requests.md
 [macos]: https://github.com/orgs/nodejs/teams/platform-macos
 [node-core-utils-credentials]: https://github.com/nodejs/node-core-utils#setting-up-credentials
 [node-core-utils-issues]: https://github.com/nodejs/node-core-utils/issues

doc/contributing/large-pull-requests.md

@@ -4,7 +4,7 @@
 * [What qualifies as a large pull request](#what-qualifies-as-a-large-pull-request)
 * [Who can open a large pull request](#who-can-open-a-large-pull-request)
 * [Requirements](#requirements)
-  * [Design document](#design-document)
+  * [Detailed pull request description](#detailed-pull-request-description)
   * [Review guide](#review-guide)
   * [Approval requirements](#approval-requirements)
   * [Dependency changes](#dependency-changes)
@@ -33,6 +33,19 @@ request, including changes in `deps/`, `test/`, `doc/`, `lib/`, `src/`, and
 Changes in `deps/` are included in this count. Dependency changes are
 sensitive because they often receive less scrutiny than first-party code.
 
+The following categories of pull requests are **excluded** from this policy,
+even if they exceed the line threshold:
+
+* Routine dependency updates (e.g., V8, ICU, undici, uvwasi) generated by
+  automation or performed by collaborators following the standard dependency
+  update process.
+* Web Platform Tests (WPT) imports and updates.
+* Other bot-issued or automated pull requests (e.g., license updates, test
+  fixture regeneration).
+
+These pull requests already have established review processes and do not
+benefit from the additional requirements described here.
+
 ## Who can open a large pull request
 
 Large pull requests may only be opened by existing
@@ -47,20 +60,19 @@ find a collaborator to champion the work.
 All large pull requests must satisfy the following requirements in addition to
 the standard [pull request requirements](./pull-requests.md).
 
-### Design document
+### Detailed pull request description
 
-A design document or detailed issue must be available when the pull request is
-opened. The design document should explain:
+The pull request description must provide sufficient context for reviewers
+to understand the change. The description should explain:
 
 * The motivation for the change.
 * The high-level approach and architecture.
 * Any alternatives that were considered and why they were rejected.
 * How the change interacts with existing subsystems.
 
-The design document can be a GitHub issue, a Markdown file in the repository,
-or an external document linked from the pull request description. It does not
-need to be shared before the work starts, but it must be available for reviewers
-when the pull request is opened.
+A thorough pull request description is sufficient. There is no requirement
+to produce a separate design document, although contributors may choose to
+link to a GitHub issue or other discussion where the design was developed.
 
 ### Review guide
 
@@ -86,9 +98,12 @@ Large pull requests follow the same approval path as semver-major changes:
 
 When a large pull request adds or modifies a dependency in `deps/`:
 
-* Dependency changes must be in a **separate commit** from the rest of the
+* Dependency changes should be in a **separate commit** from the rest of the
   pull request. This makes it easier to review the dependency update
-  independently from the first-party code changes.
+  independently from the first-party code changes. When the pull request is
+  squashed on landing, the dependency commit should be the one that carries
+  the squashed commit message, so that `git log` clearly reflects the
+  overall change.
 * The provenance and integrity of the dependency must be verifiable.
   Include documentation of how the dependency was obtained and how
   reviewers can reproduce the build artifact.
@@ -99,10 +114,12 @@ Contributors should always consider whether a large pull request can be split
 into smaller, independently reviewable pieces. Strategies include:
 
 * Landing foundational internal APIs first, then building on top of them.
-* Separating test additions from implementation changes.
-* Splitting documentation into its own pull request.
 * Landing refactoring or preparatory changes before the main feature.
 
+Each pull request in a split series should remain self-contained: it should
+include the implementation, tests, and documentation needed for that piece
+to stand on its own.
+
 ### Feature forks and branches
 
 For extremely large or complex changes that develop over time, such as adding
@@ -131,7 +148,8 @@ request.
 Reviewing a large pull request is a significant time investment. Reviewers
 should:
 
-* Read the design document and review guide before diving into the code.
+* Read the pull request description and review guide before diving into the
+  code.
 * Focus review effort on `lib/` and `src/` changes, which have the highest
   impact on the runtime. `test/` and `doc/` changes, while important, are
   lower risk.

doc/contributing/pull-requests.md

@@ -289,6 +289,9 @@ From within GitHub, opening a new pull request will present you with a
 [pull request template][]. Please try to do your best at filling out the
 details, but feel free to skip parts if you're not sure what to put.
 
+If your pull request exceeds 3000 lines of changes, see the
+[large pull requests][] guide for additional requirements.
+
 Once opened, pull requests are usually reviewed within a few days.
 
 To get feedback on your proposed change even though it is not ready
@@ -611,6 +614,7 @@ More than one subsystem may be valid for any particular issue or pull request.
 [guide for writing tests in Node.js]: writing-tests.md
 [hiding-a-comment]: https://help.github.com/articles/managing-disruptive-comments/#hiding-a-comment
 [https://ci.nodejs.org/]: https://ci.nodejs.org/
+[large pull requests]: large-pull-requests.md
 [maintaining dependencies]: ./maintaining/maintaining-dependencies.md
 [nodejs/core-validate-commit]: https://github.com/nodejs/core-validate-commit/blob/main/lib/rules/subsystem.js
 [pull request template]: https://raw.githubusercontent.com/nodejs/node/HEAD/.github/PULL_REQUEST_TEMPLATE.md