Skip to content

Commit 68d04f4

Browse files
RafaelGSSjoyeecheung
RafaelGSS
and
joyeecheung
authored
Update doc/contributing/ai-guidelines.md
Co-authored-by: Joyee Cheung <joyeec9h3@gmail.com>
1 parent 9d75ac0 commit 68d04f4

1 file changed

Lines changed: 90 additions & 87 deletions

File tree

‎doc/contributing/ai-guidelines.md‎

Lines changed: 90 additions & 87 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,21 @@
1-
# AI use policy and guidelines
2-
3-
* [Core principle](#core-principle)
4-
* [Using AI for code contributions](#using-ai-for-code-contributions)
5-
* [Using AI for communication](#using-ai-for-communication)
6-
7-
This document aligns with the [OpenJS Foundation AI Coding Assistants Policy][].
8-
9-
## Core principle
10-
11-
Node.js expects contributions to come from _people_. Contributors are free
12-
to use whatever tools they choose, including AI assistants, but such tools
13-
never replace the contributor's own understanding and responsibility.
14-
15-
Node.js requires contributors to understand and take full responsibility for
16-
every change they propose. The answer to "Why is X an improvement?" can
17-
never be "I'm not sure. The AI did it."
18-
1+
# AI use policy and guidelines
2+
3+
* [Core principle](#core-principle)
4+
* [Using AI for code contributions](#using-ai-for-code-contributions)
5+
* [Using AI for communication](#using-ai-for-communication)
6+
7+
This document aligns with the [OpenJS Foundation AI Coding Assistants Policy][].
8+
9+
## Core principle
10+
11+
Node.js expects contributions to come from _people_. Contributors are free
12+
to use whatever tools they choose, including AI assistants, but such tools
13+
never replace the contributor's own understanding and responsibility.
14+
15+
Node.js requires contributors to understand and take full responsibility for
16+
every change they propose. The answer to "Why is X an improvement?" can
17+
never be "I'm not sure. The AI did it."
18+
1919
If AI tools assisted in generating a contribution, acknowledge that honestly.
2020
Regardless of how much code is generated by AI, disclosure does not serve
2121
as a disclaimer of responsibility.
@@ -26,72 +26,75 @@ PR description, but not in the commit message, unless the context would not
2626
have made sense without mentioning the specific brand/trademark. The goal
2727
is to prevent the commit messages, which are part of the code base, from being
2828
abused for for-profit marketing.
29-
30-
Pull requests that contain AI-generated code the contributor has not
31-
personally understood, tested, and verified waste collaborator time and
32-
will be subject to closure without additional review. Contributors who
33-
repeatedly submit such changes, show no understanding of the project or
34-
its processes, or are dishonest about the use of automated assistance
35-
may be blocked from further contributions.
36-
37-
Pull requests must not be opened by automated tooling not specifically
38-
approved in advance by the project.
39-
40-
## Using AI for code contributions
41-
42-
Contributors may use AI tools to assist with contributions, but such tools
43-
never replace human judgment.
44-
45-
When using AI as a coding assistant:
46-
47-
* **Understand the codebase first.** Do not skip familiarizing yourself with
48-
the relevant subsystem. LLMs frequently produce inaccurate descriptions of
49-
Node.js internals — always verify against the actual source. When using an AI
50-
tool, ask it to cite the exact source it’s relying on, and then
51-
match the claim against that resource to verify if it holds up in the current
52-
code.
53-
54-
* **Own every line you submit.** You are responsible for all code in your
55-
pull request, regardless of how it was generated. This includes ensuring
56-
that AI-generated or AI-assisted contributions satisfy the project's
57-
[Developer's Certificate of Origin][] and licensing requirements. Be
58-
prepared to explain any change in detail during review.
59-
60-
* **Keep logical commits.** Structure commits coherently even when an LLM
61-
generates multiple changes at once. Follow the existing
62-
[commit message guidelines][].
63-
64-
* **Test thoroughly.** AI-generated code must pass the full test suite and
65-
any manually written tests relevant to the change. Existing tests should not
66-
be removed or modified without human verification. Do not rely on the LLM
67-
to assess correctness. It is crucial to manually verify the correctness of
68-
tests against the expected behavior of the feature being tested,
69-
independently of the feature's implementation.
70-
71-
* **Do not disappear.** If you open a PR, follow it through. Respond to
72-
feedback and iterate until the work lands or is explicitly closed. If you
73-
can no longer pursue it, close the PR. Stalled PRs block progress.
74-
75-
* **Do not use AI to claim "good first issue" tasks.** These issues exist to
76-
help new contributors learn the codebase and processes hands-on.
77-
78-
* **Edit generated comments critically.** LLM-produced comments are often
79-
verbose or inaccurate. Remove comments that simply restate what the code
80-
does; add comments only where the logic is non-obvious.
81-
82-
## Using AI for communication
83-
84-
Node.js values concise, precise communication that respects collaborator and contributor time.
85-
86-
* **Do not post messages generated entirely by AI** in pull requests, issues, or the
87-
project's communication channels.
88-
* **Verify accuracy** of any LLM-generated content before including it in a
89-
PR description or comment.
90-
* **Link to primary sources** — code, documentation, specifications — rather
91-
than quoting LLM answers or linking to LLM chats.
92-
* Grammar and spell-check tools are acceptable when they improve clarity and
93-
conciseness.
94-
95-
[Developer's Certificate of Origin]: ../../CONTRIBUTING.md#developers-certificate-of-origin-11
96-
[OpenJS Foundation AI Coding Assistants Policy]: https://openjsf.cdn.prismic.io/openjsf/aca4d5GXnQHGZDiZ_OpenJS_AI_Coding_Assistants_Policy.pdf
97-
[commit message guidelines]: ./pull-requests.md#commit-message-guidelines
29+
30+
Pull requests that contain AI-generated code the contributor has not
31+
personally understood, tested, and verified waste collaborator time and
32+
will be subject to closure without additional review. Contributors who
33+
repeatedly submit such changes, show no understanding of the project or
34+
its processes, or are dishonest about the use of automated assistance
35+
may be blocked from further contributions.
36+
37+
Pull requests must not be opened by automated tooling, unless specifically
38+
approved in advance by the project. To request approval, either open an issue in
39+
[nodejs/admin](https://github.com/nodejs/admin/issues), or if the automation can
40+
be done in the form of a GitHub workflow, submit a pull request to add the workflow
41+
and use the usual pull request review process to seek consensus.
42+
43+
## Using AI for code contributions
44+
45+
Contributors may use AI tools to assist with contributions, but such tools
46+
never replace human judgment.
47+
48+
When using AI as a coding assistant:
49+
50+
* **Understand the codebase first.** Do not skip familiarizing yourself with
51+
the relevant subsystem. LLMs frequently produce inaccurate descriptions of
52+
Node.js internals — always verify against the actual source. When using an AI
53+
tool, ask it to cite the exact source it’s relying on, and then
54+
match the claim against that resource to verify if it holds up in the current
55+
code.
56+
57+
* **Own every line you submit.** You are responsible for all code in your
58+
pull request, regardless of how it was generated. This includes ensuring
59+
that AI-generated or AI-assisted contributions satisfy the project's
60+
[Developer's Certificate of Origin][] and licensing requirements. Be
61+
prepared to explain any change in detail during review.
62+
63+
* **Keep logical commits.** Structure commits coherently even when an LLM
64+
generates multiple changes at once. Follow the existing
65+
[commit message guidelines][].
66+
67+
* **Test thoroughly.** AI-generated code must pass the full test suite and
68+
any manually written tests relevant to the change. Existing tests should not
69+
be removed or modified without human verification. Do not rely on the LLM
70+
to assess correctness. It is crucial to manually verify the correctness of
71+
tests against the expected behavior of the feature being tested,
72+
independently of the feature's implementation.
73+
74+
* **Do not disappear.** If you open a PR, follow it through. Respond to
75+
feedback and iterate until the work lands or is explicitly closed. If you
76+
can no longer pursue it, close the PR. Stalled PRs block progress.
77+
78+
* **Do not use AI to claim "good first issue" tasks.** These issues exist to
79+
help new contributors learn the codebase and processes hands-on.
80+
81+
* **Edit generated comments critically.** LLM-produced comments are often
82+
verbose or inaccurate. Remove comments that simply restate what the code
83+
does; add comments only where the logic is non-obvious.
84+
85+
## Using AI for communication
86+
87+
Node.js values concise, precise communication that respects collaborator and contributor time.
88+
89+
* **Do not post messages generated entirely by AI** in pull requests, issues, or the
90+
project's communication channels.
91+
* **Verify accuracy** of any LLM-generated content before including it in a
92+
PR description or comment.
93+
* **Link to primary sources** — code, documentation, specifications — rather
94+
than quoting LLM answers or linking to LLM chats.
95+
* Grammar and spell-check tools are acceptable when they improve clarity and
96+
conciseness.
97+
98+
[Developer's Certificate of Origin]: ../../CONTRIBUTING.md#developers-certificate-of-origin-11
99+
[OpenJS Foundation AI Coding Assistants Policy]: https://openjsf.cdn.prismic.io/openjsf/aca4d5GXnQHGZDiZ_OpenJS_AI_Coding_Assistants_Policy.pdf
100+
[commit message guidelines]: ./pull-requests.md#commit-message-guidelines

0 commit comments

Comments
 (0)