doc: add large pull requests contributing guide

[mcollina]

Fixes: #62752

Adds a contributing guide for large pull requests (5000+ 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.

[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

[marco-ippolito]

LGTM

[mcollina]

PTAL @trivikr @jasnell

[gurgunday]

lgtm

[trivikr]

Linter is failing. Run make format-md?