Skip to content

Commit b091d93

Browse files
panvaaduh95
panva
authored and
aduh95
committed
meta: document collaborator automation
Document how collaborators should use the commit queue, fast-track, stale automation, and saved triage views. Clarify needs-ci semantics and reviewer follow-through. Signed-off-by: Filip Skokan <[email protected]> PR-URL: #65671 Refs: nodejs/collaborators#256 Reviewed-By: Antoine du Hamel <[email protected]> Reviewed-By: Luigi Pinca <[email protected]> Reviewed-By: James M Snell <[email protected]> Reviewed-By: Trivikram Kamat <[email protected]> Reviewed-By: Matteo Collina <[email protected]> Reviewed-By: Marco Ippolito <[email protected]> Reviewed-By: Mike McCready <[email protected]> Reviewed-By: Chengzhong Wu <[email protected]>
1 parent 1304474 commit b091d93

3 files changed

Lines changed: 101 additions & 20 deletions

File tree

‎doc/contributing/collaborator-guide.md‎

Lines changed: 65 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,10 @@
55
* [Issues and pull requests](#issues-and-pull-requests)
66
* [Welcoming first-time contributors](#welcoming-first-time-contributors)
77
* [Closing issues and pull requests](#closing-issues-and-pull-requests)
8+
* [Stale issues and pull requests](#stale-issues-and-pull-requests)
89
* [Author ready pull requests](#author-ready-pull-requests)
910
* [Handling own pull requests](#handling-own-pull-requests)
11+
* [Repository triage views](#repository-triage-views)
1012
* [Security issues](#managing-security-issues)
1113
* [Accepting modifications](#accepting-modifications)
1214
* [Code reviews](#code-reviews)
@@ -66,6 +68,18 @@ request open for several days to allow for discussion. Where this does not yield
6668
evidence that the issue or pull request has relevance, close it. Remember that
6769
issues and pull requests can always be re-opened if necessary.
6870

71+
### Stale issues and pull requests
72+
73+
The [stale workflow](../../.github/workflows/stale.yml) runs on all open issues
74+
and pull requests. It adds the `stale` label after 90 days without activity and
75+
closes the item after another 30 days without activity. New activity removes
76+
the `stale` label automatically.
77+
78+
The `never-stale` label exempts both issues and pull requests from this
79+
automation. The `confirmed-bug` label also exempts issues. Reserve
80+
`never-stale` for items that need a permanent exemption. Otherwise, leave an
81+
update when an item remains relevant or close it when it does not.
82+
6983
### Author ready pull requests
7084

7185
A pull request is _author ready_ when:
@@ -77,6 +91,11 @@ A pull request is _author ready_ when:
7791
Please always add the `author ready` label to the pull request in that case.
7892
Please always remove it again as soon as the conditions are not met anymore.
7993

94+
When approving a pull request that qualifies, add `author ready` and, if a
95+
Jenkins CI run is required but has not started, `request-ci`. When the pull
96+
request author is not a collaborator, it is helpful to follow the CI run through
97+
completion and add `commit-queue` after the required CI is green.
98+
8099
### Handling own pull requests
81100

82101
When you open a pull request, [start a CI](#testing-and-ci) right away. Later,
@@ -88,6 +107,28 @@ to land but is [author ready](#author-ready-pull-requests), add the
88107
`author ready` label. If you wish to land the pull request yourself, use the
89108
"assign yourself" link to self-assign it.
90109

110+
### Repository triage views
111+
112+
The repository has several pinned
113+
[triage views](https://github.com/nodejs/node/issues/views) for managing pull
114+
requests:
115+
116+
* [PR action queue](https://github.com/nodejs/node/issues/views/15196):
117+
Non-stale, human-authored pull requests labeled `author ready` or
118+
`review wanted` that are not yet in the commit queue.
119+
* [PR attention queue](https://github.com/nodejs/node/issues/views/15058):
120+
Non-stale pull requests awaiting a second approval, requesting fast-track, or
121+
addressing flaky tests.
122+
* [Bot PRs queue](https://github.com/nodejs/node/issues/views/15198): Open,
123+
non-stale Node.js GitHub Bot and Dependabot pull requests that are not yet in
124+
the commit queue.
125+
* [My Active PRs](https://github.com/nodejs/node/issues/views/15142): Open pull
126+
requests authored by the signed-in viewer that are not yet in the commit
127+
queue.
128+
129+
Keep `author ready`, `review wanted`, `commit-queue`, and `stale` accurate so
130+
these views remain useful.
131+
91132
### Managing security issues
92133

93134
Use the process outlined in [SECURITY.md][] to report security
@@ -210,15 +251,18 @@ delay. For example:
210251
* Regressions that break the workflow (red CI or broken compilation).
211252
* Regressions that happen right before a release, or reported soon after.
212253

213-
To propose fast-tracking a pull request, apply the `fast-track` label. Then a
214-
GitHub Actions workflow will add a comment that collaborators can upvote.
254+
To propose fast-tracking a pull request, apply the `fast-track` label. A GitHub
255+
Actions workflow then adds a comment. Collaborators approve the fast-track
256+
request by adding a 👍 reaction to that comment. Reactions elsewhere on the pull
257+
request do not count.
215258

216259
If someone disagrees with the fast-tracking request, remove the label. Do not
217260
fast-track the pull request in that case.
218261

219262
The pull request can be fast-tracked if two collaborators approve the
220-
fast-tracking request. To land, the pull request itself still needs two
221-
collaborator approvals and a passing CI.
263+
fast-tracking request. Fast-track approval is additional to code-review
264+
approval, not a replacement for it. To land, the pull request itself still
265+
needs two collaborator approvals and a passing CI.
222266

223267
Collaborators can request fast-tracking of pull requests they did not author.
224268
In that case only, the request itself is also one fast-track approval. Upvote
@@ -235,6 +279,13 @@ yellow) [Jenkins CI](https://ci.nodejs.org/) is also required if the pull
235279
request contains changes that will affect the `node` binary. This is because
236280
GitHub Actions CI does not cover all the environments supported by Node.js.
237281

282+
The `needs-ci` label identifies pull requests that require a full Jenkins CI
283+
run. It is a classification, not an indication that CI is still pending. Leave
284+
it in place after CI completes. Removing it does not waive the underlying CI
285+
requirement or make a pull request eligible to land without the required
286+
checks. Removing it also makes it harder for releasers to identify the scope of
287+
a change when working on a release proposal.
288+
238289
<details>
239290
<summary>Changes that affect the `node` binary</summary>
240291

@@ -940,20 +991,29 @@ If you cannot find who to cc for a file, `git shortlog -n -s <file>` can help.
940991
### General labels
941992

942993
* `confirmed-bug`: Bugs you have verified
994+
* `commit-queue`: Pull requests queued for automated landing. See the
995+
[commit queue guide][commit-queue.md]
943996
* `discuss`: Things that need larger discussion
944997
* `fast-track`: PRs that need to land faster - see
945998
[Waiting for approvals](#waiting-for-approvals)
946999
* `feature request`: Any issue that requests a new feature
9471000
* `good first issue`: Issues suitable for newcomers to fix
1001+
* `lacks-second-approval`: An automatically managed label for queued pull
1002+
requests awaiting another approval or completion of the required wait
9481003
* `meta`: Governance, policies, procedures, etc.
1004+
* `needs-ci`: Pull requests that require a full Jenkins CI run. See
1005+
[Testing and CI](#testing-and-ci)
1006+
* `never-stale`: Issues and pull requests exempt from automatic stale handling
9491007
* `request-ci`: When this label is added to a PR, CI will be started
9501008
automatically. See [Starting a Jenkins CI job](#starting-a-jenkins-ci-job)
1009+
* `stale`: Issues and pull requests with no activity for 90 days. See
1010+
[Stale issues and pull requests](#stale-issues-and-pull-requests)
9511011
* `tsc-agenda`: Open issues and pull requests with this label will be added to
9521012
the Technical Steering Committee meeting agenda
9531013

9541014
***
9551015

956-
* `author-ready` - A pull request is _author ready_ when:
1016+
* `author ready` - A pull request is _author ready_ when:
9571017
* There is a CI run in progress or completed.
9581018
* There is at least one collaborator approval (or two TSC approvals for
9591019
semver-major pull requests).

‎doc/contributing/commit-queue.md‎

Lines changed: 26 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -3,16 +3,29 @@
33
_tl;dr: You can ask the queue to land pull requests by adding the
44
`commit-queue` label to them._
55

6-
Commit Queue is a feature for the project which simplifies the
7-
landing process by automating it via GitHub Actions. With it, collaborators can
8-
queue pull requests for landing by adding the `commit-queue` label to a PR. The
9-
selector checks readiness with `@node-core/utils`. If the pull request is only
10-
blocked on a deferrable condition, currently wait time, the queue leaves the
11-
label in place and retries later. For pull requests that are at least two days
12-
old and still waiting for a second approval, the queue adds the
13-
`lacks-second-approval` label. The queue removes that label when it removes the
14-
`commit-queue` label. Other failures continue to the existing landing and
15-
failure-reporting path.
6+
Commit Queue simplifies the landing process by automating it with GitHub
7+
Actions. Once a pull request is [author ready][] and its current CI has passed, a
8+
collaborator can queue it for landing by adding the `commit-queue` label. A
9+
second approval is not required before adding the label.
10+
11+
The queue checks readiness with `@node-core/utils`, including the required wait
12+
time measured from when the pull request was opened:
13+
14+
* Pull requests with at least two approvals must be open for 48 hours.
15+
* Pull requests with one approval must be open for seven days.
16+
* Correctly approved [fast-track pull requests][] have no minimum wait time.
17+
18+
If wait time is the only unmet condition, the queue leaves the `commit-queue`
19+
label in place and retries later. For queued pull requests that are at least two
20+
days old and still waiting for a second approval, it also adds the
21+
`lacks-second-approval` label. Another approval makes the pull request eligible
22+
for the next queue run, provided that all other requirements remain satisfied.
23+
The queue removes `lacks-second-approval` automatically when it removes
24+
`commit-queue`; collaborators do not need to remove it manually.
25+
26+
Hard failures remove `commit-queue`, add `commit-queue-failed`, and post a
27+
comment with the actionable failure reason and retry instructions. To resolve the
28+
failure, remove `commit-queue-failed`, and add `commit-queue` to retry.
1629

1730
To make the Commit Queue squash all the commits of a pull request into the
1831
first one, add the `commit-queue-squash` label.
@@ -35,3 +48,6 @@ These are the currently known limitations of the commit queue:
3548
4. Only Jenkins CI and GitHub Actions are checked (V8 CI and CITGM are ignored).
3649
5. The PR must target the `main` branch (PRs opened against other branches, such
3750
as backport PRs, are ignored).
51+
52+
[author ready]: ./collaborator-guide.md#author-ready-pull-requests
53+
[fast-track pull requests]: ./collaborator-guide.md#waiting-for-approvals

‎doc/contributing/first-contributions.md‎

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -146,8 +146,10 @@ for the technical how-tos. After a rebase, you will need a new approval from the
146146
Node.js uses two CI systems: [Jenkins](https://ci.nodejs.org/) and GitHub Actions. Jenkins is the primary
147147
CI system for testing pull requests, while GitHub Actions is used for quick checks and additional
148148
verifications. Pull requests that only touch documentation need to pass only the GitHub Actions
149-
checks. Pull requests that touch more than just documentation will be labeled `needs-ci` and will need
150-
to run the Jenkins CI before they can be merged.
149+
checks. Pull requests that affect the `node` binary also need to pass Jenkins CI before they can be
150+
merged. The automation determines this requirement from the changed files and may add the `needs-ci`
151+
label. The label describes the kind of CI required; it does not indicate that CI is still pending and
152+
remains applicable after a successful run. Removing it does not waive the CI requirement.
151153

152154
### Q: How do I trigger the CI runs?
153155

@@ -194,9 +196,12 @@ for more details on how to get started.
194196
### Q: My pull request has enough approvals and passed CI, but it still hasn't been merged. What should I do?
195197

196198
Pull requests need to be merged by collaborators or triagers (normally by applying the `commit-queue`
197-
label). The [commit queue automation](../../.github/workflows/commit-queue.yml)
198-
will verify that the pull request meets all the requirements before merging it, but the
199-
triggering of the commit queue still requires human judgement and depends on volunteers.
199+
label). Once a pull request is author ready and its current CI has passed, a collaborator can add it
200+
to the queue without waiting for a second approval. The
201+
[commit queue automation](../../.github/workflows/commit-queue.yml) verifies the requirements and
202+
waits until the pull request has either two approvals and has been open for 48 hours, or one approval
203+
and has been open for seven days. Triggering the commit queue still requires human judgement and
204+
depends on volunteers.
200205
You can ask for help either in the pull request or in the Slack channel similar
201206
to how you ask for help to get reviews and trigger CI runs.
202207

0 commit comments

Comments
 (0)