Skip to content

Commit 5a9bf7c

Browse files
joyeecheungjoyeecheung
committed
doc: add guide and answers to FAQs for first-time contributors
Signed-off-by: Joyee Cheung <joyeec9h3@gmail.com>
1 parent 040c51c commit 5a9bf7c

3 files changed

Lines changed: 225 additions & 0 deletions

File tree

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,8 @@
11
<!--
2+
If you are submitting a pull request for the first time,
3+
check out the guide for first-time contributors for tips and answers to FAQs:
4+
https://github.com/nodejs/node/blob/HEAD/doc/contributing/first-contributions.md
5+
26
Before submitting a pull request, please read:
37
48
- the CONTRIBUTING guide at https://github.com/nodejs/node/blob/HEAD/CONTRIBUTING.md

‎CONTRIBUTING.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,10 @@
11
# Contributing to Node.js
22

3+
> \[!TIP]
4+
> Contributing for the first time? Please read our
5+
> [Guide for First-Time Contributors](./doc/contributing/first-contributions.md) for tips
6+
> and answers to FAQs.
7+
38
Contributions to Node.js include code, documentation, answering user questions,
49
running the project's infrastructure, and advocating for all types of Node.js
510
users.

‎doc/contributing/first-contributions.md‎

Lines changed: 216 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,216 @@
1+
# Guides and FAQs for first-time contributors
2+
3+
Welcome to the Node.js project! This guide is complementary to the
4+
[general contribution guidelines](../../CONTRIBUTING.md)
5+
and the [pull request guidelines](./pull-requests.md), with a focus on
6+
clarifying the process for first-time contributors.
7+
8+
## Before you start
9+
10+
Read and understand [Code of Conduct](./code-of-conduct.md) before contributing to the project.
11+
12+
## Getting started with issues
13+
14+
If your first contribution is not motivated by an issue you already encounter, but you just want to help,
15+
you can find issues to work on by browsing the [issue tracker](https://github.com/nodejs/node/issues).
16+
Filter issues by the `good first issue` label to find issues that are suitable for first-time
17+
contributors. `help wanted` tracks issues that need volunteers to help but may be more challenging
18+
due to complexity or requiring special domain expertise.
19+
20+
If your first contribution is motivated by an issue you already encounter, but your proposed change
21+
is complex, introduces a new feature, breaks backward compatibility, or needs a significant refactor,
22+
it's best to open an issue to discuss the change before you start working on it.
23+
24+
### Communicating in issues
25+
26+
Node.js is a community project driven by volunteers. There are no project managers to
27+
assign issues to people. There's no need to ask for assignments on GitHub.
28+
Instead, contributors usually use comments to communicate progress.
29+
30+
Refrain from taking on issues with a comment but not following through. If the issue is
31+
straightforward, you can start working on it right away. If the task is more complex,
32+
it is okay to leave updates on the issue when you have significant findings or run into
33+
blockers before you have a pull request ready to avoid duplicate work by other contributors.
34+
35+
Avoid picking multiple issues at the same time, especially issues of the same type or area.
36+
It's better to focus on one issue and see it through to completion before picking another one.
37+
38+
During communication, be conscious of the length of your comments. Long comments can be difficult
39+
to read and may discourage others from engaging in the discussion. Refrain from pasting large
40+
blocks of code, logs, or text generated by tools. If necessary, use `<details>` tags to fold
41+
them into a collapsible section to make the discussion more readable.
42+
43+
## What NOT to do for your first contributions
44+
45+
**Refrain from automating your first contributions**. In this project, automation must
46+
be authorized and tracked explicitly. If you have an idea for automation, please open an
47+
issue to discuss it with other contributors first.
48+
49+
**Refrain from submitting large pull requests for your first contributions**. Node.js makes
50+
technical decisions through a
51+
[consensus-seeking process among its collaborators](./collaborator-guide.md#consensus-seeking),
52+
with additional community feedback taken into account. Pushing a complex change through
53+
this process can be difficult even for experienced contributors, and discouraging for
54+
first-time contributors. It's best to start with smaller, focused pull requests that
55+
address known issues, allowing you to familiarize yourself with the collaboration
56+
process first. When you have to submit a large pull request after gaining some experience,
57+
make sure to follow the [large pull request guidelines](./large-pull-requests.md).
58+
59+
## Going through the pull request review process
60+
61+
When you are ready to submit a pull request, check out the [pull request guidelines](./pull-requests.md)
62+
for the technical how-tos and explanations about the review process.
63+
64+
First-time contributors should be aware that this project uses
65+
[Developer Certificate of Origin (DCO)](https://developercertificate.org/) to manage
66+
the copyright of contributions. Make sure to
67+
[sign off your commits](./pull-requests.md#step-4-commit) (e.g., using `git commit -s`),
68+
or they cannot be merged.
69+
70+
## FAQs about pull requests
71+
72+
### Q: Why is my pull request not getting reviews?
73+
74+
In Node.js, the group of people that can approve pull requests to be merged are
75+
[the collaborators](../../GOVERNANCE.md#collaborators). While there are many of them, they
76+
are volunteers with limited bandwidth, and don't always pay attention to new
77+
pull requests, since the project is big and the volume of notifications can be overwhelming.
78+
79+
When your pull request is not getting attention, you can
80+
81+
1. Try pinging collaborators who have shown interest in the original issues.
82+
2. Try asking for help in the
83+
[#node-core channel on the OpenJS Slack](https://openjs-foundation.slack.com/archives/C019Y2T6STH).
84+
85+
**Be patient and respect the time the reviewers put in as volunteers**. People are usually
86+
happier to help if you are polite and show respect for their voluntary review efforts.
87+
88+
### Q: There are some review comments on my pull request. How should I update my pull request to address them?
89+
90+
If the review comments are left with GitHub's suggestion feature, you can apply the suggestions
91+
directly in the GitHub UI and commit the changes to your branch. Otherwise, you can push new commits to
92+
the pull request branch. See [the pull request guide](./pull-requests.md#step-9-discuss-and-update) for
93+
the technical how-tos.
94+
95+
After you push new commits, even if the previous commits have been approved, you will still need a
96+
new approval for the last commits.
97+
98+
Commits in the same pull requests are usually squashed into one commit before landing, unless
99+
there's a good justification to keep them separate - in that case, coordinate with your reviewers
100+
about this. The commits that need to be kept separate must each pass all tests on their own and
101+
follow the [commit message guidelines](./pull-requests.md#commit-message-guidelines).
102+
103+
Commit squashing is usually handled by the automation. Commits that are intended to be squashed don't
104+
have to follow the commit message guidelines, so you don't have to constantly squash them which would
105+
require new approvals/CI runs.
106+
107+
You can use
108+
[`git commit --fixup`](https://git-scm.com/docs/git-commit#Documentation/git-commit.txt---fixupamendrewordcommit)
109+
when adding new commits to your pull request to indicate how the squashing should be done
110+
(the automation uses `git rebase --autosquash` which can pick up hints left by `--fixup` and
111+
`--squash` flags).
112+
113+
### Q: I've updated my pull request, but there's no response. What should I do?
114+
115+
When you update your pull request, reviewers may not get notified automatically, depending on how
116+
they configure their notifications. They can also miss the notification, or just do not have the bandwidth
117+
to serve as volunteers in the project at the moment. You can try pinging them again to let them know about the
118+
updates. Be patient and don't overwhelm them with pings. As a reference, the general expected
119+
cadence for reviewers to respond to pull requests is around
120+
[48 hours to 7 days](./collaborator-guide.md#code-reviews).
121+
122+
### Q: There is a merge conflict in my pull request. What should I do?
123+
124+
When the target branch is updated and there is now a merge conflict in the pull request, you will
125+
need to rebase your pull request branch on top of the latest version of the target branch and
126+
resolve the conflicts locally, then force-push the updated branch to your fork.
127+
See [the pull request guide](./pull-requests.md#step-9-discuss-and-update)
128+
for the technical how-tos. After a rebase, you will need a new approval from the reviewers.
129+
130+
**Do not use the GitHub web UI to resolve merge conflicts**. The merge commit it creates can lead to issues in the CI.
131+
132+
### Q: What CI checks does my pull request need to pass?
133+
134+
Node.js uses two CI systems: [Jenkins](https://ci.nodejs.org/) and GitHub Actions. Jenkins is the primary
135+
CI system for testing pull requests, while GitHub Actions is used for quick checks and additional
136+
verifications. Pull requests that only touch documentation need to pass only the GitHub Actions
137+
checks. Pull requests that touch more than just documentation will be labeled `needs-ci` and will need
138+
to run the Jenkins CI before they can be merged.
139+
140+
### Q: How do I trigger the CI runs?
141+
142+
Because GitHub Actions workflows can access sensitive tokens, for your first pull request in
143+
the repository, a collaborator needs to explicitly approve the workflow run. Once you
144+
have one pull request merged, later pull requests will trigger GitHub Actions automatically without
145+
needing approval.
146+
147+
Due to similar security concerns, Jenkins CI runs can only be triggered by collaborators and
148+
triagers who have the permission to apply the `request-ci` label. But because the Jenkins CI tests
149+
a large matrix of platforms and configurations, and the infrastructure resources are limited,
150+
Jenkins CI runs always have to be triggered by humans and won't run automatically. When your
151+
pull request is ready for CI, you will need to ask for help from collaborators or triagers to
152+
trigger the Jenkins CI runs.
153+
154+
It takes time for a volunteer to verify that the pull request does not contain malicious code
155+
before approving the CI runs. Similar to the review process, be patient and respectful of
156+
the volunteers' time when you are asking for help to trigger the CI runs, this helps build
157+
trust to make future contributions smoother.
158+
159+
### Q: The CI runs showed some failures that seem unrelated to my change. What should I do?
160+
161+
The Node.js CIs are known to be flaky. Consult the daily reports in
162+
[the reliability repository](https://github.com/nodejs/reliability/issues) to see if the same failures
163+
are showing up in other pull requests - if they do, it's very likely that they are unrelated to your
164+
change. In this case, you can ignore those failures and ask for help to trigger the CI runs again -
165+
often, these failures are intermittent and will disappear in the next run.
166+
167+
Tip: the flakes have been plaguing the project for a long time because there aren't enough volunteers
168+
to fix them. If you have the time and interest, try volunteering to fix the ones that you are
169+
confident with! See the
170+
[reliability repository README](https://github.com/nodejs/reliability#protocols-in-improving-ci-reliability)
171+
for more details on how to get started.
172+
173+
### Q: My pull request has enough approvals and passed CI, but it still hasn't been merged. What should I do?
174+
175+
Pull requests need to be merged by collaborators or triagers (normally by applying the `commit-queue`
176+
label). The [commit queue automation](../../.github/workflows/commit-queue.yml)
177+
will verify that the pull request meets all the requirements before merging it, but the
178+
triggering of the commit queue still requires human judgement and depends on volunteers.
179+
You can ask for help either in the pull request or in the slack channel similar
180+
to how you ask for help to get reviews and trigger CI runs.
181+
182+
### Q: There's a comment saying that my pull request is landed, but instead I see my pull request closed, what happened?
183+
184+
In this project, pull requests are typically merged by the
185+
[commit queue](../../.github/workflows/commit-queue.yml) to amend the commit with
186+
necessary metadata, not through the GitHub UI. Sometimes the automation or the collaborator
187+
performing the merge can update the branches in a way that GitHub recognizes it as a merge
188+
and shows a purple "merged" status, sometimes it's not the case.
189+
As long as you see a comment saying that your pull request is landed, and the commits do appear
190+
in the target branch of your pull request, don't worry, it means the change has been effectively
191+
merged, regardless of what GitHub shows.
192+
193+
### Q: When will my change be released?
194+
195+
Commits merged into the `main` are released according to the release schedule,
196+
which are displayed in the [Release Working Group's pinned issues](https://github.com/nodejs/Release/issues).
197+
198+
If the pull request is not labeled `dont-land-*` or `semver-major`, it will be included in the next
199+
"current" release. If the change is labeled `dont-land-*`, it will be held back from release until
200+
the label is removed. If the change is labeled `semver-major`, it will only be included in the next
201+
major release, which may take months, depending on when the pull request is merged.
202+
203+
### Q: Someone commented in my pull request that the change doesn't land cleanly on a release branch, what should I do?
204+
205+
Commits landed into `main` are backported to the release staging branches using `git cherry-pick`
206+
before they can be released. This process is typically performed by volunteers from the Release
207+
Working Group, but it can also be performed by other volunteers.
208+
209+
When the volunteers cherry-pick your commits to the release branches, if there's a git conflict, or
210+
there's a test failure caused by the change, and the volunteer cannot confidently resolve these
211+
issues on their own, they will leave this comment in the original pull request to ask for help.
212+
When you see this comment, try backporting by opening a backport pull request yourself.
213+
See [the backporting guide](./backporting-to-release-lines.md) for the technical how-tos.
214+
215+
If no one follows through with the backporting, your pull request may not be included in
216+
any releases until the next major release cut from the `main` branch.

0 commit comments

Comments
 (0)