Contributions to Node.js include code, documentation, answering user questions,

running the project's infrastructure, and advocating for all types of Node.js

users.

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.

Read and understand [Code of Conduct](./code-of-conduct.md) before contributing to the project.

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.

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.

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

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.

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.

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.

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

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.

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.

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

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.

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.

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.

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.