From 457fa6706210df7cc65b07a8576e4b412fcbd909 Mon Sep 17 00:00:00 2001
From: Joyee Cheung <joyeec9h3@gmail.com>
Date: Tue, 30 Jun 2026 15:07:26 +0200
Subject: [PATCH] doc: add guide and answers to FAQs for first-time
 contributors

Signed-off-by: Joyee Cheung <joyeec9h3@gmail.com>
PR-URL: https://github.com/nodejs/node/pull/63685
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
Reviewed-By: Moshe Atlow <moshe@atlow.co.il>
Reviewed-By: Filip Skokan <panva.ip@gmail.com>
---
 .github/PULL_REQUEST_TEMPLATE.md        |   4 +
 CONTRIBUTING.md                         |   5 +
 doc/contributing/first-contributions.md | 235 ++++++++++++++++++++++++
 3 files changed, 244 insertions(+)
 create mode 100644 doc/contributing/first-contributions.md

diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index 936c2a06125..3950bc702eb 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 e22f23543e5..b47b9868461 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 00000000000..0d4bf7f35a6
--- /dev/null
+++ b/doc/contributing/first-contributions.md
@@ -0,0 +1,235 @@
+# 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 can be useful to open an issue to discuss whether the change or its design is acceptable before
+working out the implementation details. The issue can be opened before you send the pull request,
+or along side your pull request (in which case, it's better to keep the pull request in draft mode).
+
+Straightforward or non-controversial changes, such as an obvious bug fix or a small refactor, don't
+usually benefit from discussions in a separate issue, and can be sent directly as a pull request.
+
+### 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).
+
+**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)
+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 away don't
+have to follow the commit message guidelines - only the ones whose commit message will be kept after
+squashing do. If your commits are already approved and the CI has passed on them, don't worry
+about squashing them yourself - the automation will take care of it during landing.
+
+The automation uses `git rebase --autosquash` which can pick up hints left by
+[`--fixup`](https://git-scm.com/docs/git-commit#Documentation/git-commit.txt---fixupamendrewordcommit) and
+[`--squash`](https://git-scm.com/docs/git-commit#Documentation/git-commit.txt---squashcommit) flags of the
+`git commit` command. You can use these flags when adding new commits to your pull request to indicate how
+the squashing should be done.
+
+### 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?
+
+If the pull request is not `semver-major`, commits merged into the `main` branch are typically
+first released in next "Current" release. After spending at least two weeks in the "Current" release,
+a change that is not `semver-major` will be eligible to be included in the next "LTS" releases.
+The "Current" and "LTS" releases follow schedules that are tracked in the
+[Release Working Group's pinned issues](https://github.com/nodejs/Release/issues).
+
+If the change is labeled `dont-land-*`, it will be held back from releases in the specified branch until
+the label is removed.
+
+If the change is labeled `semver-major`, it will not be included in the next "Current" release.
+Instead, it will need to wait until the next major release cut from the `main` branch to be included in a
+release. This may take up to months, depending on when the pull request is merged.
+
+Commits on `main` are backported to the release staging branches using `git cherry-pick` before they can be released.
+See [the backporting guide](./backporting-to-release-lines.md). This process is typically performed by
+volunteers from the Release Working Group, but other volunteers can also help. If your change isn't making
+progress in the backporting process as expected, you can ask for help in the Slack channel and see if
+volunteering to backport your change yourself would help.
+
+### Q: Someone commented in my pull request that the change doesn't land cleanly on a release branch, what should I do?
+
+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.