Welcome to the Node.js project! This guide is complementary to the general contribution guidelines and the pull request guidelines, with a focus on clarifying the process for first-time contributors.
Read and understand Code of Conduct 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.
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, 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.
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 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) to manage
the copyright of contributions. Make sure to
sign off your commits (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. 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
- Try pinging collaborators who have shown interest in the original issues.
- Try asking for help in the #node-core channel on the OpenJS Slack.
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 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.
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 and
--squash 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.
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 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 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.
Q: The Jenkins CI failed, but when I clicked the CI link, it shows "Access Denied". What should I do?
Read access to the Jenkins CI is restricted to a few teams in the Node.js organization. You will
need to ask a member of these teams (for example, any of the collaborators) to show you the details
of the failures. If after a day or so from a collaborator triggering a Jenkins CI your PR shows a
failure in either the node-test-pull-request or node-test-commit-* checks it's worth adding a
comment to the PR asking what tests are failed, as the collaborator may not realise that you cannot
see the results directly.
The Node.js CIs are known to be flaky. Consult the daily reports in the reliability repository 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 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
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 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.
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. 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 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.