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 <panva.ip@gmail.com>
PR-URL: #65671
Refs: nodejs/collaborators#256
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Marco Ippolito <marcoippolito54@gmail.com>
Reviewed-By: Mike McCready <66998419+MikeMcC399@users.noreply.github.com>
Reviewed-By: Chengzhong Wu <legendecas@gmail.com>

Author: panva

doc/contributing/collaborator-guide.md

@@ -5,8 +5,10 @@
 * [Issues and pull requests](#issues-and-pull-requests)
   * [Welcoming first-time contributors](#welcoming-first-time-contributors)
   * [Closing issues and pull requests](#closing-issues-and-pull-requests)
+  * [Stale issues and pull requests](#stale-issues-and-pull-requests)
   * [Author ready pull requests](#author-ready-pull-requests)
   * [Handling own pull requests](#handling-own-pull-requests)
+  * [Repository triage views](#repository-triage-views)
   * [Security issues](#managing-security-issues)
 * [Accepting modifications](#accepting-modifications)
   * [Code reviews](#code-reviews)
@@ -66,6 +68,18 @@ request open for several days to allow for discussion. Where this does not yield
 evidence that the issue or pull request has relevance, close it. Remember that
 issues and pull requests can always be re-opened if necessary.
 
+### Stale issues and pull requests
+
+The [stale workflow](../../.github/workflows/stale.yml) runs on all open issues
+and pull requests. It adds the `stale` label after 90 days without activity and
+closes the item after another 30 days without activity. New activity removes
+the `stale` label automatically.
+
+The `never-stale` label exempts both issues and pull requests from this
+automation. The `confirmed-bug` label also exempts issues. Reserve
+`never-stale` for items that need a permanent exemption. Otherwise, leave an
+update when an item remains relevant or close it when it does not.
+
 ### Author ready pull requests
 
 A pull request is _author ready_ when:
@@ -77,6 +91,11 @@ A pull request is _author ready_ when:
 Please always add the `author ready` label to the pull request in that case.
 Please always remove it again as soon as the conditions are not met anymore.
 
+When approving a pull request that qualifies, add `author ready` and, if a
+Jenkins CI run is required but has not started, `request-ci`. When the pull
+request author is not a collaborator, it is helpful to follow the CI run through
+completion and add `commit-queue` after the required CI is green.
+
 ### Handling own pull requests
 
 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
 `author ready` label. If you wish to land the pull request yourself, use the
 "assign yourself" link to self-assign it.
 
+### Repository triage views
+
+The repository has several pinned
+[triage views](https://github.com/nodejs/node/issues/views) for managing pull
+requests:
+
+* [PR action queue](https://github.com/nodejs/node/issues/views/15196):
+  Non-stale, human-authored pull requests labeled `author ready` or
+  `review wanted` that are not yet in the commit queue.
+* [PR attention queue](https://github.com/nodejs/node/issues/views/15058):
+  Non-stale pull requests awaiting a second approval, requesting fast-track, or
+  addressing flaky tests.
+* [Bot PRs queue](https://github.com/nodejs/node/issues/views/15198): Open,
+  non-stale Node.js GitHub Bot and Dependabot pull requests that are not yet in
+  the commit queue.
+* [My Active PRs](https://github.com/nodejs/node/issues/views/15142): Open pull
+  requests authored by the signed-in viewer that are not yet in the commit
+  queue.
+
+Keep `author ready`, `review wanted`, `commit-queue`, and `stale` accurate so
+these views remain useful.
+
 ### Managing security issues
 
 Use the process outlined in [SECURITY.md][] to report security
@@ -210,15 +251,18 @@ delay. For example:
   * Regressions that break the workflow (red CI or broken compilation).
   * Regressions that happen right before a release, or reported soon after.
 
-To propose fast-tracking a pull request, apply the `fast-track` label. Then a
-GitHub Actions workflow will add a comment that collaborators can upvote.
+To propose fast-tracking a pull request, apply the `fast-track` label. A GitHub
+Actions workflow then adds a comment. Collaborators approve the fast-track
+request by adding a 👍 reaction to that comment. Reactions elsewhere on the pull
+request do not count.
 
 If someone disagrees with the fast-tracking request, remove the label. Do not
 fast-track the pull request in that case.
 
 The pull request can be fast-tracked if two collaborators approve the
-fast-tracking request. To land, the pull request itself still needs two
-collaborator approvals and a passing CI.
+fast-tracking request. Fast-track approval is additional to code-review
+approval, not a replacement for it. To land, the pull request itself still
+needs two collaborator approvals and a passing CI.
 
 Collaborators can request fast-tracking of pull requests they did not author.
 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
 request contains changes that will affect the `node` binary. This is because
 GitHub Actions CI does not cover all the environments supported by Node.js.
 
+The `needs-ci` label identifies pull requests that require a full Jenkins CI
+run. It is a classification, not an indication that CI is still pending. Leave
+it in place after CI completes. Removing it does not waive the underlying CI
+requirement or make a pull request eligible to land without the required
+checks. Removing it also makes it harder for releasers to identify the scope of
+a change when working on a release proposal.
+
 <details>
 <summary>Changes that affect the `node` binary</summary>
 
@@ -940,20 +991,29 @@ If you cannot find who to cc for a file, `git shortlog -n -s <file>` can help.
 ### General labels
 
 * `confirmed-bug`: Bugs you have verified
+* `commit-queue`: Pull requests queued for automated landing. See the
+  [commit queue guide][commit-queue.md]
 * `discuss`: Things that need larger discussion
 * `fast-track`: PRs that need to land faster - see
   [Waiting for approvals](#waiting-for-approvals)
 * `feature request`: Any issue that requests a new feature
 * `good first issue`: Issues suitable for newcomers to fix
+* `lacks-second-approval`: An automatically managed label for queued pull
+  requests awaiting another approval or completion of the required wait
 * `meta`: Governance, policies, procedures, etc.
+* `needs-ci`: Pull requests that require a full Jenkins CI run. See
+  [Testing and CI](#testing-and-ci)
+* `never-stale`: Issues and pull requests exempt from automatic stale handling
 * `request-ci`: When this label is added to a PR, CI will be started
   automatically. See [Starting a Jenkins CI job](#starting-a-jenkins-ci-job)
+* `stale`: Issues and pull requests with no activity for 90 days. See
+  [Stale issues and pull requests](#stale-issues-and-pull-requests)
 * `tsc-agenda`: Open issues and pull requests with this label will be added to
   the Technical Steering Committee meeting agenda
 
 ***
 
-* `author-ready` - A pull request is _author ready_ when:
+* `author ready` - A pull request is _author ready_ when:
   * There is a CI run in progress or completed.
   * There is at least one collaborator approval (or two TSC approvals for
     semver-major pull requests).

doc/contributing/commit-queue.md

@@ -3,16 +3,29 @@
 _tl;dr: You can ask the queue to land pull requests by adding the
 `commit-queue` label to them._
 
-Commit Queue is a feature for the project which simplifies the
-landing process by automating it via GitHub Actions. With it, collaborators can
-queue pull requests for landing by adding the `commit-queue` label to a PR. The
-selector checks readiness with `@node-core/utils`. If the pull request is only
-blocked on a deferrable condition, currently wait time, the queue leaves the
-label in place and retries later. For pull requests that are at least two days
-old and still waiting for a second approval, the queue adds the
-`lacks-second-approval` label. The queue removes that label when it removes the
-`commit-queue` label. Other failures continue to the existing landing and
-failure-reporting path.
+Commit Queue simplifies the landing process by automating it with GitHub
+Actions. Once a pull request is [author ready][] and its current CI has passed, a
+collaborator can queue it for landing by adding the `commit-queue` label. A
+second approval is not required before adding the label.
+
+The queue checks readiness with `@node-core/utils`, including the required wait
+time measured from when the pull request was opened:
+
+* Pull requests with at least two approvals must be open for 48 hours.
+* Pull requests with one approval must be open for seven days.
+* Correctly approved [fast-track pull requests][] have no minimum wait time.
+
+If wait time is the only unmet condition, the queue leaves the `commit-queue`
+label in place and retries later. For queued pull requests that are at least two
+days old and still waiting for a second approval, it also adds the
+`lacks-second-approval` label. Another approval makes the pull request eligible
+for the next queue run, provided that all other requirements remain satisfied.
+The queue removes `lacks-second-approval` automatically when it removes
+`commit-queue`; collaborators do not need to remove it manually.
+
+Hard failures remove `commit-queue`, add `commit-queue-failed`, and post a
+comment with the actionable failure reason and retry instructions. To resolve the
+failure, remove `commit-queue-failed`, and add `commit-queue` to retry.
 
 To make the Commit Queue squash all the commits of a pull request into the
 first one, add the `commit-queue-squash` label.
@@ -35,3 +48,6 @@ These are the currently known limitations of the commit queue:
 4. Only Jenkins CI and GitHub Actions are checked (V8 CI and CITGM are ignored).
 5. The PR must target the `main` branch (PRs opened against other branches, such
    as backport PRs, are ignored).
+
+[author ready]: ./collaborator-guide.md#author-ready-pull-requests
+[fast-track pull requests]: ./collaborator-guide.md#waiting-for-approvals

doc/contributing/first-contributions.md

@@ -146,8 +146,10 @@ for the technical how-tos. After a rebase, you will need a new approval from the
 Node.js uses two CI systems: [Jenkins](https://ci.nodejs.org/) and GitHub Actions. Jenkins is the primary
 CI system for testing pull requests, while GitHub Actions is used for quick checks and additional
 verifications. Pull requests that only touch documentation need to pass only the GitHub Actions
-checks. Pull requests that touch more than just documentation will be labeled `needs-ci` and will need
-to run the Jenkins CI before they can be merged.
+checks. Pull requests that affect the `node` binary also need to pass Jenkins CI before they can be
+merged. The automation determines this requirement from the changed files and may add the `needs-ci`
+label. The label describes the kind of CI required; it does not indicate that CI is still pending and
+remains applicable after a successful run. Removing it does not waive the CI requirement.
 
 ### Q: How do I trigger the CI runs?
 
@@ -194,9 +196,12 @@ for more details on how to get started.
 ### Q: My pull request has enough approvals and passed CI, but it still hasn't been merged. What should I do?
 
 Pull requests need to be merged by collaborators or triagers (normally by applying the `commit-queue`
-label). The [commit queue automation](../../.github/workflows/commit-queue.yml)
-will verify that the pull request meets all the requirements before merging it, but the
-triggering of the commit queue still requires human judgement and depends on volunteers.
+label). Once a pull request is author ready and its current CI has passed, a collaborator can add it
+to the queue without waiting for a second approval. The
+[commit queue automation](../../.github/workflows/commit-queue.yml) verifies the requirements and
+waits until the pull request has either two approvals and has been open for 48 hours, or one approval
+and has been open for seven days. Triggering the commit queue still requires human judgement and
+depends on volunteers.
 You can ask for help either in the pull request or in the Slack channel similar
 to how you ask for help to get reviews and trigger CI runs.