From 5a9bf7cee8eddc3dd71ce954bb81cfc7cac67407 Mon Sep 17 00:00:00 2001
From: Joyee Cheung <joyeec9h3@gmail.com>
Date: Sun, 31 May 2026 18:24:09 +0200
Subject: [PATCH 1/3] doc: add guide and answers to FAQs for first-time
 contributors

Signed-off-by: Joyee Cheung <joyeec9h3@gmail.com>
---
 .github/PULL_REQUEST_TEMPLATE.md        |   4 +
 CONTRIBUTING.md                         |   5 +
 doc/contributing/first-contributions.md | 216 ++++++++++++++++++++++++
 3 files changed, 225 insertions(+)
 create mode 100644 doc/contributing/first-contributions.md

diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index 936c2a06125795..3950bc702eb58b 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -1,4 +1,8 @@
 <!--
+If you are submitting a pull request for the first time,
+check out the guide for first-time contributors for tips and answers to FAQs:
+https://github.com/nodejs/node/blob/HEAD/doc/contributing/first-contributions.md
+
 Before submitting a pull request, please read:
 
 - the CONTRIBUTING guide at https://github.com/nodejs/node/blob/HEAD/CONTRIBUTING.md
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index e22f23543e5ccc..b47b9868461be5 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,5 +1,10 @@
 # Contributing to Node.js
 
+> \[!TIP]
+> Contributing for the first time? Please read our
+> [Guide for First-Time Contributors](./doc/contributing/first-contributions.md) for tips
+> and answers to FAQs.
+
 Contributions to Node.js include code, documentation, answering user questions,
 running the project's infrastructure, and advocating for all types of Node.js
 users.
diff --git a/doc/contributing/first-contributions.md b/doc/contributing/first-contributions.md
new file mode 100644
index 00000000000000..14a6c58d3ac571
--- /dev/null
+++ b/doc/contributing/first-contributions.md
@@ -0,0 +1,216 @@
+# Guides and FAQs for first-time contributors
+
+Welcome to the Node.js project! This guide is complementary to the
+[general contribution guidelines](../../CONTRIBUTING.md)
+and the [pull request guidelines](./pull-requests.md), with a focus on
+clarifying the process for first-time contributors.
+
+## Before you start
+
+Read and understand [Code of Conduct](./code-of-conduct.md) before contributing to the project.
+
+## Getting started with issues
+
+If your first contribution is not motivated by an issue you already encounter, but you just want to help,
+you can find issues to work on by browsing the [issue tracker](https://github.com/nodejs/node/issues).
+Filter issues by the `good first issue` label to find issues that are suitable for first-time
+contributors. `help wanted` tracks issues that need volunteers to help but may be more challenging
+due to complexity or requiring special domain expertise.
+
+If your first contribution is motivated by an issue you already encounter, but your proposed change
+is complex, introduces a new feature, breaks backward compatibility, or needs a significant refactor,
+it's best to open an issue to discuss the change before you start working on it.
+
+### Communicating in issues
+
+Node.js is a community project driven by volunteers. There are no project managers to
+assign issues to people. There's no need to ask for assignments on GitHub.
+Instead, contributors usually use comments to communicate progress.
+
+Refrain from taking on issues with a comment but not following through. If the issue is
+straightforward, you can start working on it right away. If the task is more complex,
+it is okay to leave updates on the issue when you have significant findings or run into
+blockers before you have a pull request ready to avoid duplicate work by other contributors.
+
+Avoid picking multiple issues at the same time, especially issues of the same type or area.
+It's better to focus on one issue and see it through to completion before picking another one.
+
+During communication, be conscious of the length of your comments. Long comments can be difficult
+to read and may discourage others from engaging in the discussion. Refrain from pasting large
+blocks of code, logs, or text generated by tools. If necessary, use `<details>` tags to fold
+them into a collapsible section to make the discussion more readable.
+
+## What NOT to do for your first contributions
+
+**Refrain from automating your first contributions**. In this project, automation must
+be authorized and tracked explicitly. If you have an idea for automation, please open an
+issue to discuss it with other contributors first.
+
+**Refrain from submitting large pull requests for your first contributions**. Node.js makes
+technical decisions through a
+[consensus-seeking process among its collaborators](./collaborator-guide.md#consensus-seeking),
+with additional community feedback taken into account. Pushing a complex change through
+this process can be difficult even for experienced contributors, and discouraging for
+first-time contributors. It's best to start with smaller, focused pull requests that
+address known issues, allowing you to familiarize yourself with the collaboration
+process first. When you have to submit a large pull request after gaining some experience,
+make sure to follow the [large pull request guidelines](./large-pull-requests.md).
+
+## Going through the pull request review process
+
+When you are ready to submit a pull request, check out the [pull request guidelines](./pull-requests.md)
+for the technical how-tos and explanations about the review process.
+
+First-time contributors should be aware that this project uses
+[Developer Certificate of Origin (DCO)](https://developercertificate.org/) to manage
+the copyright of contributions. Make sure to
+[sign off your commits](./pull-requests.md#step-4-commit) (e.g., using `git commit -s`),
+or they cannot be merged.
+
+## FAQs about pull requests
+
+### Q: Why is my pull request not getting reviews?
+
+In Node.js, the group of people that can approve pull requests to be merged are
+[the collaborators](../../GOVERNANCE.md#collaborators). While there are many of them, they
+are volunteers with limited bandwidth, and don't always pay attention to new
+pull requests, since the project is big and the volume of notifications can be overwhelming.
+
+When your pull request is not getting attention, you can
+
+1. Try pinging collaborators who have shown interest in the original issues.
+2. Try asking for help in the
+   [#node-core channel on the OpenJS Slack](https://openjs-foundation.slack.com/archives/C019Y2T6STH).
+
+**Be patient and respect the time the reviewers put in as volunteers**. People are usually
+happier to help if you are polite and show respect for their voluntary review efforts.
+
+### Q: There are some review comments on my pull request. How should I update my pull request to address them?
+
+If the review comments are left with GitHub's suggestion feature, you can apply the suggestions
+directly in the GitHub UI and commit the changes to your branch. Otherwise, you can push new commits to
+the pull request branch. See [the pull request guide](./pull-requests.md#step-9-discuss-and-update) for
+the technical how-tos.
+
+After you push new commits, even if the previous commits have been approved, you will still need a
+new approval for the last commits.
+
+Commits in the same pull requests are usually squashed into one commit before landing, unless
+there's a good justification to keep them separate - in that case, coordinate with your reviewers
+about this. The commits that need to be kept separate must each pass all tests on their own and
+follow the [commit message guidelines](./pull-requests.md#commit-message-guidelines).
+
+Commit squashing is usually handled by the automation. Commits that are intended to be squashed don't
+have to follow the commit message guidelines, so you don't have to constantly squash them which would
+require new approvals/CI runs.
+
+You can use
+[`git commit --fixup`](https://git-scm.com/docs/git-commit#Documentation/git-commit.txt---fixupamendrewordcommit)
+when adding new commits to your pull request to indicate how the squashing should be done
+(the automation uses `git rebase --autosquash` which can pick up hints left by `--fixup` and
+`--squash` flags).
+
+### Q: I've updated my pull request, but there's no response. What should I do?
+
+When you update your pull request, reviewers may not get notified automatically, depending on how
+they configure their notifications. They can also miss the notification, or just do not have the bandwidth
+to serve as volunteers in the project at the moment. You can try pinging them again to let them know about the
+updates. Be patient and don't overwhelm them with pings. As a reference, the general expected
+cadence for reviewers to respond to pull requests is around
+[48 hours to 7 days](./collaborator-guide.md#code-reviews).
+
+### Q: There is a merge conflict in my pull request. What should I do?
+
+When the target branch is updated and there is now a merge conflict in the pull request, you will
+need to rebase your pull request branch on top of the latest version of the target branch and
+resolve the conflicts locally, then force-push the updated branch to your fork.
+See [the pull request guide](./pull-requests.md#step-9-discuss-and-update)
+for the technical how-tos. After a rebase, you will need a new approval from the reviewers.
+
+**Do not use the GitHub web UI to resolve merge conflicts**. The merge commit it creates can lead to issues in the CI.
+
+### Q: What CI checks does my pull request need to pass?
+
+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.
+
+### Q: How do I trigger the CI runs?
+
+Because GitHub Actions workflows can access sensitive tokens, for your first pull request in
+the repository, a collaborator needs to explicitly approve the workflow run. Once you
+have one pull request merged, later pull requests will trigger GitHub Actions automatically without
+needing approval.
+
+Due to similar security concerns, Jenkins CI runs can only be triggered by collaborators and
+triagers who have the permission to apply the `request-ci` label. But because the Jenkins CI tests
+a large matrix of platforms and configurations, and the infrastructure resources are limited,
+Jenkins CI runs always have to be triggered by humans and won't run automatically. When your
+pull request is ready for CI, you will need to ask for help from collaborators or triagers to
+trigger the Jenkins CI runs.
+
+It takes time for a volunteer to verify that the pull request does not contain malicious code
+before approving the CI runs. Similar to the review process, be patient and respectful of
+the volunteers' time when you are asking for help to trigger the CI runs, this helps build
+trust to make future contributions smoother.
+
+### Q: The CI runs showed some failures that seem unrelated to my change. What should I do?
+
+The Node.js CIs are known to be flaky. Consult the daily reports in
+[the reliability repository](https://github.com/nodejs/reliability/issues) to see if the same failures
+are showing up in other pull requests - if they do, it's very likely that they are unrelated to your
+change. In this case, you can ignore those failures and ask for help to trigger the CI runs again -
+often, these failures are intermittent and will disappear in the next run.
+
+Tip: the flakes have been plaguing the project for a long time because there aren't enough volunteers
+to fix them. If you have the time and interest, try volunteering to fix the ones that you are
+confident with! See the
+[reliability repository README](https://github.com/nodejs/reliability#protocols-in-improving-ci-reliability)
+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.
+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.
+
+### Q: There's a comment saying that my pull request is landed, but instead I see my pull request closed, what happened?
+
+In this project, pull requests are typically merged by the
+[commit queue](../../.github/workflows/commit-queue.yml) to amend the commit with
+necessary metadata, not through the GitHub UI. Sometimes the automation or the collaborator
+performing the merge can update the branches in a way that GitHub recognizes it as a merge
+and shows a purple "merged" status, sometimes it's not the case.
+As long as you see a comment saying that your pull request is landed, and the commits do appear
+in the target branch of your pull request, don't worry, it means the change has been effectively
+merged, regardless of what GitHub shows.
+
+### Q: When will my change be released?
+
+Commits merged into the `main` are released according to the release schedule,
+which are displayed in the [Release Working Group's pinned issues](https://github.com/nodejs/Release/issues).
+
+If the pull request is not labeled `dont-land-*` or `semver-major`, it will be included in the next
+"current" release. If the change is labeled `dont-land-*`, it will be held back from release until
+the label is removed. If the change is labeled `semver-major`, it will only be included in the next
+major release, which may take months, depending on when the pull request is merged.
+
+### Q: Someone commented in my pull request that the change doesn't land cleanly on a release branch, what should I do?
+
+Commits landed into `main` are backported to the release staging branches using `git cherry-pick`
+before they can be released. This process is typically performed by volunteers from the Release
+Working Group, but it can also be performed by other volunteers.
+
+When the volunteers cherry-pick your commits to the release branches, if there's a git conflict, or
+there's a test failure caused by the change, and the volunteer cannot confidently resolve these
+issues on their own, they will leave this comment in the original pull request to ask for help.
+When you see this comment, try backporting by opening a backport pull request yourself.
+See [the backporting guide](./backporting-to-release-lines.md) for the technical how-tos.
+
+If no one follows through with the backporting, your pull request may not be included in
+any releases until the next major release cut from the `main` branch.

From a6ad67a3bb6bc24c29aca146fc960571e315de85 Mon Sep 17 00:00:00 2001
From: Joyee Cheung <joyeec9h3@gmail.com>
Date: Mon, 1 Jun 2026 01:51:34 +0200
Subject: [PATCH 2/3] fixup! doc: add guide and answers to FAQs for first-time
 contributors

Co-authored-by: Antoine du Hamel <duhamelantoine1995@gmail.com>
---
 doc/contributing/first-contributions.md | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/doc/contributing/first-contributions.md b/doc/contributing/first-contributions.md
index 14a6c58d3ac571..4fa55c29233bf6 100644
--- a/doc/contributing/first-contributions.md
+++ b/doc/contributing/first-contributions.md
@@ -56,6 +56,11 @@ address known issues, allowing you to familiarize yourself with the collaboratio
 process first. When you have to submit a large pull request after gaining some experience,
 make sure to follow the [large pull request guidelines](./large-pull-requests.md).
 
+**Refrain from opening new Pull Requests before the first one has been approved**.
+This gives others the first impression that you are flooding the project.
+It's OK to not get everything right on the first try, but if you open PRs faster
+than they are reviewed, you are wasting an opportunity to improve, and can overwhelm
+both yourself and your reviewers with notifications.
 ## Going through the pull request review process
 
 When you are ready to submit a pull request, check out the [pull request guidelines](./pull-requests.md)

From 5e67908ae54828446845309de46da47c16a6e328 Mon Sep 17 00:00:00 2001
From: Joyee Cheung <joyeec9h3@gmail.com>
Date: Mon, 1 Jun 2026 01:52:12 +0200
Subject: [PATCH 3/3] fixup! doc: add guide and answers to FAQs for first-time
 contributors

---
 doc/contributing/first-contributions.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/doc/contributing/first-contributions.md b/doc/contributing/first-contributions.md
index 4fa55c29233bf6..3608b957496f64 100644
--- a/doc/contributing/first-contributions.md
+++ b/doc/contributing/first-contributions.md
@@ -61,6 +61,7 @@ This gives others the first impression that you are flooding the project.
 It's OK to not get everything right on the first try, but if you open PRs faster
 than they are reviewed, you are wasting an opportunity to improve, and can overwhelm
 both yourself and your reviewers with notifications.
+
 ## Going through the pull request review process
 
 When you are ready to submit a pull request, check out the [pull request guidelines](./pull-requests.md)