node/doc/contributing/first-contributions.md

# 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.