doc: add large pull requests contributing guide

[mcollina]

Fixes: #62752

Adds a contributing guide for large pull requests (3000+ lines), covering:

• Threshold definition and applicability
• Restriction to collaborators only
• Design document and review guide requirements
• Two TSC approvals (same as semver-major)
• Dependency change separation
• Feature fork workflow in separate repositories
• Reviewer guidance

[nodejs-github-bot]

Review requested:

• @nodejs/tsc

[panva]

• We should link to it from CONTRIBUTING.md, pull-requests.md, collaborator-guide.md (or some subset of those)
• We should exclude routine dependency/wpt/test bot-issued PRs, this can either be excluded explicitly with additional rules or by changing the classification put forth by the Overview or What qualifies as a large pull request sections
• dependency changes in a separate commit is at odds with having each commit self-contained, this is fine when the commits get squashed but the first commit's message is used for the squash so the first commit would be the non-deps changes? seems odd and counter-intuitive
• Design document - I 100% discourage linking outside documents, a detailed PR description should also suffice, 3000 can easily be hit with just thorough test coverage for an otherwise trivial change, how would a design document help such PRs?
• Both Separating test additions from implementation changes. and Splitting documentation into its own pull request. strategies to avoiding large PRs are contrary to what we usually request of contributions. Those strategies only work when the contribution isn't "done" or "shipped" and is excluded from builds.

[RafaelGSS]

I love it. LGTM

[joyeecheung]

The specification here doesn't seem very clear:

1. What are 3000 line of changes: deletion and addition combined? Or just one of them? Splitting a flaky test monolith to avoid hiding regressions for example can easily pass the threshold even though there's not really an interesting architecture to explain and 2 TSC review seems like overkill
2. What happens when a PR initially isn't big but grows to be bigger as more tests/docs are added?

[mcollina]

The specification here doesn't seem very clear:

1. What are 3000 line of changes: deletion and addition combined? Or just one of them? Splitting a flaky test monolith to avoid hiding regressions for example can easily pass the threshold even though there's not really an interesting architecture to explain and 2 TSC review seems like overkill

We have to draw a line, and this is as good as any. I proposed 5k but I was asked to lower it.
We need this to be "easy" to check from the GitHub interface.

I would be happier with a 3k of non-test/non-doc changes, but that would require better tooling, which I'd prefer to avoid creating now.

What would work for you?

2. What happens when a PR initially isn't big but grows to be bigger as more tests/docs are added?

The number that matters is at landing time.

[ShogunPanda]

The specification here doesn't seem very clear:

1. What are 3000 line of changes: deletion and addition combined? Or just one of them? Splitting a flaky test monolith to avoid hiding regressions for example can easily pass the threshold even though there's not really an interesting architecture to explain and 2 TSC review seems like overkill

In the document it says: A pull request is considered large when it exceeds **3000 lines** of combined additions and deletions..

So ADD + (- DEL) > 3000

2. What happens when a PR initially isn't big but grows to be bigger as more tests/docs are added?

I would say as soon as it reaches the threshold the new rules apply. This also means that if with further commits the PR shrinks, rules do not apply anymore.
I guess the commit-queue bot must have a rule to ultimately enforce this.

[jasnell]

FYI, I've added the new large-pr label that we can use to explicitly marge large PRs that would fall under this policy

[jasnell]

ADD + ( -DEL) > 3000 is more complicated than I think it needs to be. I'd prefer just to look at additions but happy to go with consensus if others agree with the proposed alternative.

[jasnell]

@nodejs/tsc ... we could use some more TSC scrutiny on this policy change.

[UlisesGascon]

Suggested change

	* Organize commits in a logical sequence so that reviewers can follow the progression of the change incrementally, rather than reviewing the entire diff at once.

Organize commits in a logical sequence that tells a clear story of the change, allowing reviewers to follow the progression incrementally. Ideally we can follow the author's train of thought step by step rather than parsing a monolithic diff 🤔

[mcollina]

This is in direct conflict with what has been asked by @joyeecheung and others.

(This is how I operate, btw, creating a PR in small increments).

[joyeecheung]

Our tools support autoquash commits and I think we should just lean into using autosquash commits. The commits themselves should always be in the shape that's suitable to be merged into main. That is, a sequence like this (that reflect the chain of thought of the authors but not how it should land)

1. commit1
2. commit2
3. address A's comment (touch both 1 and 2)
4. address B's comment (touch both 2 and 3)
5. address C's comment (touch 1)

is not the right way to stack commits - the later commits are actually harder to review because you then need to track other comments and the author have to later squash them correctly, and it's a chore to review that the final squash is correct, especially considering we have the hard requirement that commits landed must be themselves individually passing the test for bisect to work.

The way I have always being doing is:

1. commit1
2. commit2
3. fixup! commit1
4. fixup! commit2
5. fixup! commit1

Then reviewers can mentally connect the fixups with the original commits, and the author do not have to squash commits themselves manually - our commit queue tooling support autosquash, so 1, 3, 5 would be squashed together and 2, 4 would be squashed together automatically at the time of landing.

We already have guidelines for how to group commits, I think whether the PR is big or not doesn't make a lot of difference in this, we can just reference that https://github.com/nodejs/node/blob/main/doc/contributing/pull-requests.md#step-4-commit

[ShogunPanda]

ADD + ( -DEL) > 3000 is more complicated than I think it needs to be. I'd prefer just to look at additions but happy to go with consensus if others agree with the proposed alternative.

To be honest I don't have strong opinions on this. I just wrote out how I interpreted the rule to make sure we're on the same page.

Thinking about it, my formula above probably would easily trigger this limit. Just making out an example, if I have a JS function which body is 100 lines long and I wrap the entire body inside a if (horrible, but...why not? :)), it already is 2 pure additions and then 100 removed, 100 lines added (because of indentation). We're already at 202. With something like this you often reach 3000.

So either we only count additions or we raised the combined limit.

[mcollina]

I've updated it to to be ADDED - DELETED > LIMIT

[panva]

3000 is very easy to hit with simple refactors, consider ignoring whitespace for this "check". Ignoring whitespace can make 15 files changed, 935 insertions(+), 789 deletions(-) change i'm working on a 15 files changed, 297 insertions(+), 151 deletions(-) one.