How to add a triager to Node.js (the exact PR path)

I’ve watched “one-line docs PRs” burn an hour because someone edited the wrong file.

Node.js v20.19.6 includes a perfect example of the right way to do this: PR #59562 merged commit e7f6f04758, which updated the triager entry in README.md, and the release notes later listed it.

What “add triager” really means in nodejs/node

This is boring on purpose.

You add a name to a public list so the project can track who helps triage issues. You do not “grant access” with this docs change, but people treat these lists like an audit trail, so accuracy matters.

• Real upstream example: PR #59562 landed commit e7f6f04758 (“doc: add Miles Guicent as triager”) and Node.js v20.19.6 release notes later listed it.
• File that changed in the example: README.md. That detail matters because contributors often guess “collaborators.md” and send a PR that goes nowhere.

Before you touch anything, confirm the authoritative file

Do this first.

If you skip it, you will probably pass CI and still get a “wrong file” review comment two days later. In the v20.19.6 triager change, the project updated README.md, so start there and search the repo for the current triager list format.

• Fast repo search: Use GitHub search in nodejs/node for “Triagers” and for an existing triager’s GitHub handle. Edit the file that already holds those entries.
• When multiple files disagree: Stop and ask in the PR or open an issue. I have seen projects update a data file but forget the docs page, then both sides drift for months.

Step-by-step: the PR I’d want to review

Keep it small.

A triager addition should look like a two-minute diff and a clean PR description, with zero “while I’m here” edits. Ignore the GitHub commit count. It’s a vanity metric.

• 1) Fork and clone: Fork nodejs/node, then clone your fork. Add upstream as a remote so you can rebase cleanly later.
• 2) Create a focused branch: Use a name that tells reviewers what changed, like doc/add-triager-miles-guicent.
• 3) Edit the file and match existing formatting: In the example release, the change happened in README.md. Add the new entry in the same section and keep spacing, punctuation, and link style identical.
• 4) Run the project’s documented checks: Do not guess “npm run lint” unless nodejs/node docs say to. Run whatever CONTRIBUTING.md recommends for docs changes, then push.
• 5) Commit message: Use the same style the project already uses. The referenced commit used “doc: add Miles Guicent as triager”.
• 6) Sign-off requirements: Node.js typically expects DCO-style Signed-off-by. Check CONTRIBUTING.md and make your commit match the repo rules before you open the PR.
• 7) Open the PR and link proof: In your PR body, link to the onboarding context or approval. If you have nothing to link, say who requested the change and where.
• 8) Respond to review quickly: Reviewers will nitpick names, ordering, and formatting. They should. This list becomes historical record.

I don’t trust “known issues: none” from any project. I also don’t trust “tiny docs change” PRs that touch five files.

Common ways this goes sideways (and quick fixes)

This bit me once.

I edited a “collaborators” file that looked right, CI went green, then a maintainer pointed out the real source lived in README.md. Now I always search for the existing entry format before I type anything.

• CI fails on markdown or spelling: Fix exactly what the bot complains about. Avoid reformatting unrelated paragraphs.
• DCO or sign-off check fails: Amend the commit and add the required sign-off line, then force-push your branch. Yes, even for a docs PR.
• Wrong file edited: Move the change to the file the project treats as authoritative, then drop the earlier edit. Keep the PR tight.
• Merge conflicts: Rebase on the current target branch and rerun the checks. This almost never hurts for a one-line change, unless someone reordered the same list.

How to verify it landed (don’t guess)

Check the receipts.

For the v20.19.6 example, you can verify three things: the PR merged (PR #59562), the commit exists (e7f6f04758), and the Node.js v20.19.6 release notes list that commit. If any one of those is missing, your change did not land the way you think it did.

• PR proof: Confirm the PR shows “Merged” and all required checks passed.
• Commit proof: Open the commit and confirm the file diff matches what you intended.
• Release proof: Search the v20.19.6 release notes page for the commit subject line.

What I’d do next (optional, but smart)

So.

If you run a big project, add a tiny check that blocks duplicate triager entries and broken GitHub links. Some folks skip automation for docs-only changes. I don’t, but I get it.

• Add a PR checklist item: “Correct file, correct section, formatting matches, sign-off check passes.”
• Create an onboarding follow-up: Add a link in the PR to the onboarding issue or note who approved the role change.
• Automation idea: Add a simple CI job that validates the triager list format. There’s probably a better way to test this, but…