doc: add guide and answers to FAQs for first-time contributors

Signed-off-by: Joyee Cheung <joyeec9h3@gmail.com>

Author: joyeecheung

.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

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.

doc/contributing/first-contributions.md

@@ -0,0 +1,215 @@
+# 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. It does not have project managers to assign
+issues to people. Contributors usually use comments to communicate progress instead.
+
+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
+
+#### 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.
+
+#### 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).
+
+#### 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).
+
+#### 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.
+
+#### 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.
+
+#### 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.
+
+#### 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.
+
+#### 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.
+
+#### 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.
+
+#### 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.
+
+#### 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.