From 522a34e0b1754902ce2146bfe4f311b5b62bfe81 Mon Sep 17 00:00:00 2001 From: RafaelGSS Date: Wed, 4 Mar 2026 18:23:19 -0300 Subject: [PATCH 01/11] doc: create ai-guidelines and include to CONTRIBUTING Co-Authored-By: Beth Griggs --- CONTRIBUTING.md | 10 ++++++ doc/contributing/ai-guidelines.md | 57 +++++++++++++++++++++++++++++++ 2 files changed, 67 insertions(+) create mode 100644 doc/contributing/ai-guidelines.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 54296234a304d8..06e0fcffabac13 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -20,6 +20,7 @@ works. * [Issues](#issues) * [Pull Requests](#pull-requests) * [Automation and bots](#automation-and-bots) +* [AI Use Policy and Guidelines](#ai-use-policy-and-guidelines) * [Developer's Certificate of Origin 1.1](#developers-certificate-of-origin-11) ## [Code of Conduct](./doc/contributing/code-of-conduct.md) @@ -60,6 +61,15 @@ by an automation that was not authorized by Node.js collaborators are subject to immediate moderation enforcement on the automation and owner without notice. +## [AI Use Policy and Guidelines](./doc/contributing/ai-guidelines.md) + +Node.js expects contributors to understand and take full responsibility for +every change they propose. Pull requests consisting of AI-generated code the +contributor has not personally understood, tested, and verified will be closed +without review. + +See [details on our AI use policy and guidelines](./doc/contributing/ai-guidelines.md). + ## Developer's Certificate of Origin 1.1 ```text diff --git a/doc/contributing/ai-guidelines.md b/doc/contributing/ai-guidelines.md new file mode 100644 index 00000000000000..c3a8d950051b3f --- /dev/null +++ b/doc/contributing/ai-guidelines.md @@ -0,0 +1,57 @@ +# AI use policy and guidelines + +* [Core principle](#core-principle) +* [Using AI for code contributions](#using-ai-for-code-contributions) +* [Using AI for communication](#using-ai-for-communication) + +## Core principle + +Node.js expects contributors to understand and take full responsibility for +every change they propose. The answer to "Why is X an improvement?" should +never be "I'm not sure. The AI did it." + +Pull requests that consist of AI-generated code the contributor has not +personally understood, tested, and verified waste collaborator time and +will be closed without review. + +## Using AI for code contributions + +AI tools may assist contributors, but must not replace contributor judgment. +When using AI as a coding assistant: + +* **Understand the codebase first.** Do not skip familiarizing yourself with + the relevant subsystem. LLMs frequently produce inaccurate descriptions of + Node.js internals — always verify against the actual source. + +* **Own every line you submit.** You are responsible for all code in your + pull request, regardless of how it was generated. Be prepared to explain + any change in detail during review. + +* **Keep logical commits.** Structure commits coherently even when an LLM + generates multiple changes at once. Follow the existing + [commit message guidelines][]. + +* **Test thoroughly.** AI-generated code must pass the full test suite and + any manually written tests relevant to the change. Do not rely on the LLM + to assess correctness. + +* **Edit generated comments critically.** LLM-produced comments are often + verbose or inaccurate. Remove comments that simply restate what the code + does; add comments only where the logic is non-obvious. + +## Using AI for communication + +Node.js values concise, precise communication that respects collaborator time. + +* **Do not post AI-generated messages** in pull requests, issues, or the + project's communication channels. +* **Verify accuracy** of any LLM-generated content before including it in a + PR description or comment. +* **Complete pull request templates fully** rather than replacing them with + LLM-generated summaries. +* **Link to primary sources** — code, documentation, specifications — rather + than quoting LLM answers. +* Grammar and spell-check tools are acceptable when they improve clarity and + conciseness. + +[commit message guidelines]: ./pull-requests.md#commit-message-guidelines From 2587c60753ab89252489a2dd2c203ced3c79abd1 Mon Sep 17 00:00:00 2001 From: Rafael Gonzaga Date: Thu, 5 Mar 2026 11:03:50 -0300 Subject: [PATCH 02/11] Apply suggestions from code review Co-authored-by: Aditi <62544124+Aditi-1400@users.noreply.github.com> Co-authored-by: Joyee Cheung --- doc/contributing/ai-guidelines.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/doc/contributing/ai-guidelines.md b/doc/contributing/ai-guidelines.md index c3a8d950051b3f..0981c37705af63 100644 --- a/doc/contributing/ai-guidelines.md +++ b/doc/contributing/ai-guidelines.md @@ -21,7 +21,10 @@ When using AI as a coding assistant: * **Understand the codebase first.** Do not skip familiarizing yourself with the relevant subsystem. LLMs frequently produce inaccurate descriptions of - Node.js internals — always verify against the actual source. + Node.js internals — always verify against the actual source. When using an AI + tool, ask it to cite the exact source files/PRs/docs it’s relying on, and then + match the claim against that resource to verify if it holds up in the current + code. * **Own every line you submit.** You are responsible for all code in your pull request, regardless of how it was generated. Be prepared to explain @@ -32,7 +35,8 @@ When using AI as a coding assistant: [commit message guidelines][]. * **Test thoroughly.** AI-generated code must pass the full test suite and - any manually written tests relevant to the change. Do not rely on the LLM + any manually written tests relevant to the change. Existing Tests should not + be removed or modified without human verification. Do not rely on the LLM to assess correctness. * **Edit generated comments critically.** LLM-produced comments are often From 5b63cb839cad813a2c86f6d108f1cf5613e5dc2d Mon Sep 17 00:00:00 2001 From: Rafael Gonzaga Date: Fri, 13 Mar 2026 10:55:41 -0300 Subject: [PATCH 03/11] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Tobias Nießen Co-authored-by: Antoine du Hamel Co-authored-by: Mike McCready <66998419+MikeMcC399@users.noreply.github.com> Co-authored-by: Efe --- CONTRIBUTING.md | 2 +- doc/contributing/ai-guidelines.md | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 06e0fcffabac13..d93e4590954a06 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -65,7 +65,7 @@ without notice. Node.js expects contributors to understand and take full responsibility for every change they propose. Pull requests consisting of AI-generated code the -contributor has not personally understood, tested, and verified will be closed +contributor has not personally understood, tested, and verified might be closed without review. See [details on our AI use policy and guidelines](./doc/contributing/ai-guidelines.md). diff --git a/doc/contributing/ai-guidelines.md b/doc/contributing/ai-guidelines.md index 0981c37705af63..065784786d6816 100644 --- a/doc/contributing/ai-guidelines.md +++ b/doc/contributing/ai-guidelines.md @@ -12,7 +12,7 @@ never be "I'm not sure. The AI did it." Pull requests that consist of AI-generated code the contributor has not personally understood, tested, and verified waste collaborator time and -will be closed without review. +will be subject to closure without additional review. ## Using AI for code contributions @@ -35,7 +35,7 @@ When using AI as a coding assistant: [commit message guidelines][]. * **Test thoroughly.** AI-generated code must pass the full test suite and - any manually written tests relevant to the change. Existing Tests should not + any manually written tests relevant to the change. Existing tests should not be removed or modified without human verification. Do not rely on the LLM to assess correctness. @@ -47,7 +47,7 @@ When using AI as a coding assistant: Node.js values concise, precise communication that respects collaborator time. -* **Do not post AI-generated messages** in pull requests, issues, or the +* **Do not post messages generated entirely by AI** in pull requests, issues, or the project's communication channels. * **Verify accuracy** of any LLM-generated content before including it in a PR description or comment. From 2243a91762b8dcf08dec64036e0017116ef02e96 Mon Sep 17 00:00:00 2001 From: RafaelGSS Date: Fri, 13 Mar 2026 13:39:15 -0300 Subject: [PATCH 04/11] fixup! Apply suggestions from code review --- doc/contributing/ai-guidelines.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/doc/contributing/ai-guidelines.md b/doc/contributing/ai-guidelines.md index 065784786d6816..f51c0b9bf867ac 100644 --- a/doc/contributing/ai-guidelines.md +++ b/doc/contributing/ai-guidelines.md @@ -22,8 +22,8 @@ When using AI as a coding assistant: * **Understand the codebase first.** Do not skip familiarizing yourself with the relevant subsystem. LLMs frequently produce inaccurate descriptions of Node.js internals — always verify against the actual source. When using an AI - tool, ask it to cite the exact source files/PRs/docs it’s relying on, and then - match the claim against that resource to verify if it holds up in the current + tool, ask it to cite the exact source files/PRs/docs it’s relying on, and then + match the claim against that resource to verify if it holds up in the current code. * **Own every line you submit.** You are responsible for all code in your @@ -39,6 +39,10 @@ When using AI as a coding assistant: be removed or modified without human verification. Do not rely on the LLM to assess correctness. +* **Do not disappear.** If you open a PR, follow it through. Respond to + feedback and iterate until the work lands or is explicitly closed. If you + can no longer pursue it, close the PR. Stalled PRs block progress. + * **Edit generated comments critically.** LLM-produced comments are often verbose or inaccurate. Remove comments that simply restate what the code does; add comments only where the logic is non-obvious. From c935e3d55ef5e893c19c366abe51123411b26ea3 Mon Sep 17 00:00:00 2001 From: RafaelGSS Date: Wed, 1 Apr 2026 16:16:00 -0300 Subject: [PATCH 05/11] fixup! fixup! Apply suggestions from code review --- CONTRIBUTING.md | 4 +-- doc/contributing/ai-guidelines.md | 45 +++++++++++++++++++++++-------- 2 files changed, 36 insertions(+), 13 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d93e4590954a06..b5fa93a85b9f90 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -63,9 +63,9 @@ without notice. ## [AI Use Policy and Guidelines](./doc/contributing/ai-guidelines.md) -Node.js expects contributors to understand and take full responsibility for +Node.js requires contributors to understand and take full responsibility for every change they propose. Pull requests consisting of AI-generated code the -contributor has not personally understood, tested, and verified might be closed +contributor has not personally understood, tested, and verified will likely be closed without review. See [details on our AI use policy and guidelines](./doc/contributing/ai-guidelines.md). diff --git a/doc/contributing/ai-guidelines.md b/doc/contributing/ai-guidelines.md index f51c0b9bf867ac..ab5fd438ba72fd 100644 --- a/doc/contributing/ai-guidelines.md +++ b/doc/contributing/ai-guidelines.md @@ -4,31 +4,51 @@ * [Using AI for code contributions](#using-ai-for-code-contributions) * [Using AI for communication](#using-ai-for-communication) +This document aligns with the [OpenJS Foundation AI Coding Assistants Policy][]. + ## Core principle -Node.js expects contributors to understand and take full responsibility for -every change they propose. The answer to "Why is X an improvement?" should +Node.js expects contributions to come from _people_. Contributors are free +to use whatever tools they choose, including AI assistants, but such tools +never replace the contributor's own understanding and responsibility. + +Node.js requires contributors to understand and take full responsibility for +every change they propose. The answer to "Why is X an improvement?" can never be "I'm not sure. The AI did it." +If AI tools assisted in generating a contribution, that should be +acknowledged honestly (e.g., via an `Assisted-by:` tag in the commit +metadata) so that reviewers have appropriate context. + Pull requests that consist of AI-generated code the contributor has not personally understood, tested, and verified waste collaborator time and -will be subject to closure without additional review. +will be subject to closure without additional review. Contributors who +repeatedly submit such changes, show no understanding of the project or +its processes, or are dishonest about the use of automated assistance +may be blocked from further contributions. + +Pull requests must not be opened by automated tooling not specifically +approved in advance by the project. ## Using AI for code contributions -AI tools may assist contributors, but must not replace contributor judgment. +Contributors may use AI tools to assist with contributions, but such tools +never replace human judgment. + When using AI as a coding assistant: * **Understand the codebase first.** Do not skip familiarizing yourself with the relevant subsystem. LLMs frequently produce inaccurate descriptions of Node.js internals — always verify against the actual source. When using an AI - tool, ask it to cite the exact source files/PRs/docs it’s relying on, and then + tool, ask it to cite the exact source it’s relying on, and then match the claim against that resource to verify if it holds up in the current code. * **Own every line you submit.** You are responsible for all code in your - pull request, regardless of how it was generated. Be prepared to explain - any change in detail during review. + pull request, regardless of how it was generated. This includes ensuring + that AI-generated or AI-assisted contributions satisfy the project's + [Developer's Certificate of Origin][] and licensing requirements. Be + prepared to explain any change in detail during review. * **Keep logical commits.** Structure commits coherently even when an LLM generates multiple changes at once. Follow the existing @@ -43,23 +63,26 @@ When using AI as a coding assistant: feedback and iterate until the work lands or is explicitly closed. If you can no longer pursue it, close the PR. Stalled PRs block progress. +* **Do not use AI to claim "good first issue" tasks.** These issues exist to + help new contributors learn the codebase and processes hands-on. + * **Edit generated comments critically.** LLM-produced comments are often verbose or inaccurate. Remove comments that simply restate what the code does; add comments only where the logic is non-obvious. ## Using AI for communication -Node.js values concise, precise communication that respects collaborator time. +Node.js values concise, precise communication that respects collaborator and contributor time. * **Do not post messages generated entirely by AI** in pull requests, issues, or the project's communication channels. * **Verify accuracy** of any LLM-generated content before including it in a PR description or comment. -* **Complete pull request templates fully** rather than replacing them with - LLM-generated summaries. * **Link to primary sources** — code, documentation, specifications — rather - than quoting LLM answers. + than quoting LLM answers or linking to LLM chats. * Grammar and spell-check tools are acceptable when they improve clarity and conciseness. [commit message guidelines]: ./pull-requests.md#commit-message-guidelines +[Developer's Certificate of Origin]: ../../CONTRIBUTING.md#developers-certificate-of-origin-11 +[OpenJS Foundation AI Coding Assistants Policy]: https://openjsf.cdn.prismic.io/openjsf/aca4d5GXnQHGZDiZ_OpenJS_AI_Coding_Assistants_Policy.pdf From 2eeadf6e61c46112995b13321acadde18d0205e0 Mon Sep 17 00:00:00 2001 From: RafaelGSS Date: Wed, 1 Apr 2026 16:30:42 -0300 Subject: [PATCH 06/11] fixup! fixup! fixup! Apply suggestions from code review --- doc/contributing/ai-guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/contributing/ai-guidelines.md b/doc/contributing/ai-guidelines.md index ab5fd438ba72fd..45054bbc9089f1 100644 --- a/doc/contributing/ai-guidelines.md +++ b/doc/contributing/ai-guidelines.md @@ -83,6 +83,6 @@ Node.js values concise, precise communication that respects collaborator and con * Grammar and spell-check tools are acceptable when they improve clarity and conciseness. -[commit message guidelines]: ./pull-requests.md#commit-message-guidelines [Developer's Certificate of Origin]: ../../CONTRIBUTING.md#developers-certificate-of-origin-11 +[commit message guidelines]: ./pull-requests.md#commit-message-guidelines [OpenJS Foundation AI Coding Assistants Policy]: https://openjsf.cdn.prismic.io/openjsf/aca4d5GXnQHGZDiZ_OpenJS_AI_Coding_Assistants_Policy.pdf From 7944826e1987e5be99d805acf59c67abf751fb61 Mon Sep 17 00:00:00 2001 From: RafaelGSS Date: Mon, 4 May 2026 10:14:05 -0300 Subject: [PATCH 07/11] fixup! Apply suggestions from code review --- CONTRIBUTING.md | 2 +- doc/contributing/ai-guidelines.md | 6 ++++-- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b5fa93a85b9f90..dcf14866e74537 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -64,7 +64,7 @@ without notice. ## [AI Use Policy and Guidelines](./doc/contributing/ai-guidelines.md) Node.js requires contributors to understand and take full responsibility for -every change they propose. Pull requests consisting of AI-generated code the +every change they propose. Pull requests containing AI-generated code the contributor has not personally understood, tested, and verified will likely be closed without review. diff --git a/doc/contributing/ai-guidelines.md b/doc/contributing/ai-guidelines.md index 45054bbc9089f1..3b0a24385d0a9d 100644 --- a/doc/contributing/ai-guidelines.md +++ b/doc/contributing/ai-guidelines.md @@ -20,7 +20,7 @@ If AI tools assisted in generating a contribution, that should be acknowledged honestly (e.g., via an `Assisted-by:` tag in the commit metadata) so that reviewers have appropriate context. -Pull requests that consist of AI-generated code the contributor has not +Pull requests that contain AI-generated code the contributor has not personally understood, tested, and verified waste collaborator time and will be subject to closure without additional review. Contributors who repeatedly submit such changes, show no understanding of the project or @@ -57,7 +57,9 @@ When using AI as a coding assistant: * **Test thoroughly.** AI-generated code must pass the full test suite and any manually written tests relevant to the change. Existing tests should not be removed or modified without human verification. Do not rely on the LLM - to assess correctness. + to assess correctness. It is crucial to manually verify the correctness of + tests against the expected behavior of the feature being tested, + independently of the feature's implementation. * **Do not disappear.** If you open a PR, follow it through. Respond to feedback and iterate until the work lands or is explicitly closed. If you From d8668b60cea8914f53e57f1d7dd310030ec17b89 Mon Sep 17 00:00:00 2001 From: RafaelGSS Date: Mon, 4 May 2026 12:16:09 -0300 Subject: [PATCH 08/11] fixup! Apply suggestions from code review --- doc/contributing/ai-guidelines.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/doc/contributing/ai-guidelines.md b/doc/contributing/ai-guidelines.md index 3b0a24385d0a9d..5e0f5a26782a65 100644 --- a/doc/contributing/ai-guidelines.md +++ b/doc/contributing/ai-guidelines.md @@ -16,9 +16,10 @@ Node.js requires contributors to understand and take full responsibility for every change they propose. The answer to "Why is X an improvement?" can never be "I'm not sure. The AI did it." -If AI tools assisted in generating a contribution, that should be -acknowledged honestly (e.g., via an `Assisted-by:` tag in the commit -metadata) so that reviewers have appropriate context. +If AI tools assisted in generating a contribution, acknowledge that honestly +in the commit metadata using an `Assisted-by:` trailer. This applies +regardless of how much of the work was AI-generated — the contributor +remains the sole author and bears full responsibility for every line. Pull requests that contain AI-generated code the contributor has not personally understood, tested, and verified waste collaborator time and From 0c298297645cf3295b61fedc326be6197a65215d Mon Sep 17 00:00:00 2001 From: RafaelGSS Date: Mon, 4 May 2026 13:25:52 -0300 Subject: [PATCH 09/11] fixup! fixup! Apply suggestions from code review --- doc/contributing/ai-guidelines.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/doc/contributing/ai-guidelines.md b/doc/contributing/ai-guidelines.md index 5e0f5a26782a65..0f5f52e03510bb 100644 --- a/doc/contributing/ai-guidelines.md +++ b/doc/contributing/ai-guidelines.md @@ -20,6 +20,10 @@ If AI tools assisted in generating a contribution, acknowledge that honestly in the commit metadata using an `Assisted-by:` trailer. This applies regardless of how much of the work was AI-generated — the contributor remains the sole author and bears full responsibility for every line. +If the disclosure involves trademarks or commercial brands, it's recommended to +anonymize it in the commit message or only mention it in the PR description, +but not in the commit message, unless the context would not have made sense +without mentioning the specific brand/trademark. Pull requests that contain AI-generated code the contributor has not personally understood, tested, and verified waste collaborator time and @@ -87,5 +91,5 @@ Node.js values concise, precise communication that respects collaborator and con conciseness. [Developer's Certificate of Origin]: ../../CONTRIBUTING.md#developers-certificate-of-origin-11 -[commit message guidelines]: ./pull-requests.md#commit-message-guidelines [OpenJS Foundation AI Coding Assistants Policy]: https://openjsf.cdn.prismic.io/openjsf/aca4d5GXnQHGZDiZ_OpenJS_AI_Coding_Assistants_Policy.pdf +[commit message guidelines]: ./pull-requests.md#commit-message-guidelines From 9d75ac02ec71643a1640df70aa6660f890cdea7b Mon Sep 17 00:00:00 2001 From: Rafael Gonzaga Date: Tue, 5 May 2026 13:08:30 -0300 Subject: [PATCH 10/11] Apply suggestions from code review Co-authored-by: Joyee Cheung --- doc/contributing/ai-guidelines.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/doc/contributing/ai-guidelines.md b/doc/contributing/ai-guidelines.md index 0f5f52e03510bb..2b442c911a5253 100644 --- a/doc/contributing/ai-guidelines.md +++ b/doc/contributing/ai-guidelines.md @@ -16,14 +16,16 @@ Node.js requires contributors to understand and take full responsibility for every change they propose. The answer to "Why is X an improvement?" can never be "I'm not sure. The AI did it." -If AI tools assisted in generating a contribution, acknowledge that honestly -in the commit metadata using an `Assisted-by:` trailer. This applies -regardless of how much of the work was AI-generated — the contributor -remains the sole author and bears full responsibility for every line. -If the disclosure involves trademarks or commercial brands, it's recommended to -anonymize it in the commit message or only mention it in the PR description, -but not in the commit message, unless the context would not have made sense -without mentioning the specific brand/trademark. +If AI tools assisted in generating a contribution, acknowledge that honestly. +Regardless of how much code is generated by AI, disclosure does not serve +as a disclaimer of responsibility. +The contributor remains the sole author and bears full responsibility for every line. +If the disclosure involves trademarks or commercial brands, it's recommended to +anonymize it in the commit message or only mention the brand/trademark in the +PR description, but not in the commit message, unless the context would not +have made sense without mentioning the specific brand/trademark. The goal +is to prevent the commit messages, which are part of the code base, from being +abused for for-profit marketing. Pull requests that contain AI-generated code the contributor has not personally understood, tested, and verified waste collaborator time and From 68d04f4cabc35d0f50a0028f286fdffdfbae3d30 Mon Sep 17 00:00:00 2001 From: Rafael Gonzaga Date: Tue, 5 May 2026 13:58:21 -0300 Subject: [PATCH 11/11] Update doc/contributing/ai-guidelines.md Co-authored-by: Joyee Cheung --- doc/contributing/ai-guidelines.md | 177 +++++++++++++++--------------- 1 file changed, 90 insertions(+), 87 deletions(-) diff --git a/doc/contributing/ai-guidelines.md b/doc/contributing/ai-guidelines.md index 2b442c911a5253..7ed7361bd921b3 100644 --- a/doc/contributing/ai-guidelines.md +++ b/doc/contributing/ai-guidelines.md @@ -1,21 +1,21 @@ -# AI use policy and guidelines - -* [Core principle](#core-principle) -* [Using AI for code contributions](#using-ai-for-code-contributions) -* [Using AI for communication](#using-ai-for-communication) - -This document aligns with the [OpenJS Foundation AI Coding Assistants Policy][]. - -## Core principle - -Node.js expects contributions to come from _people_. Contributors are free -to use whatever tools they choose, including AI assistants, but such tools -never replace the contributor's own understanding and responsibility. - -Node.js requires contributors to understand and take full responsibility for -every change they propose. The answer to "Why is X an improvement?" can -never be "I'm not sure. The AI did it." - +# AI use policy and guidelines + +* [Core principle](#core-principle) +* [Using AI for code contributions](#using-ai-for-code-contributions) +* [Using AI for communication](#using-ai-for-communication) + +This document aligns with the [OpenJS Foundation AI Coding Assistants Policy][]. + +## Core principle + +Node.js expects contributions to come from _people_. Contributors are free +to use whatever tools they choose, including AI assistants, but such tools +never replace the contributor's own understanding and responsibility. + +Node.js requires contributors to understand and take full responsibility for +every change they propose. The answer to "Why is X an improvement?" can +never be "I'm not sure. The AI did it." + If AI tools assisted in generating a contribution, acknowledge that honestly. Regardless of how much code is generated by AI, disclosure does not serve as a disclaimer of responsibility. @@ -26,72 +26,75 @@ PR description, but not in the commit message, unless the context would not have made sense without mentioning the specific brand/trademark. The goal is to prevent the commit messages, which are part of the code base, from being abused for for-profit marketing. - -Pull requests that contain AI-generated code the contributor has not -personally understood, tested, and verified waste collaborator time and -will be subject to closure without additional review. Contributors who -repeatedly submit such changes, show no understanding of the project or -its processes, or are dishonest about the use of automated assistance -may be blocked from further contributions. - -Pull requests must not be opened by automated tooling not specifically -approved in advance by the project. - -## Using AI for code contributions - -Contributors may use AI tools to assist with contributions, but such tools -never replace human judgment. - -When using AI as a coding assistant: - -* **Understand the codebase first.** Do not skip familiarizing yourself with - the relevant subsystem. LLMs frequently produce inaccurate descriptions of - Node.js internals — always verify against the actual source. When using an AI - tool, ask it to cite the exact source it’s relying on, and then - match the claim against that resource to verify if it holds up in the current - code. - -* **Own every line you submit.** You are responsible for all code in your - pull request, regardless of how it was generated. This includes ensuring - that AI-generated or AI-assisted contributions satisfy the project's - [Developer's Certificate of Origin][] and licensing requirements. Be - prepared to explain any change in detail during review. - -* **Keep logical commits.** Structure commits coherently even when an LLM - generates multiple changes at once. Follow the existing - [commit message guidelines][]. - -* **Test thoroughly.** AI-generated code must pass the full test suite and - any manually written tests relevant to the change. Existing tests should not - be removed or modified without human verification. Do not rely on the LLM - to assess correctness. It is crucial to manually verify the correctness of - tests against the expected behavior of the feature being tested, - independently of the feature's implementation. - -* **Do not disappear.** If you open a PR, follow it through. Respond to - feedback and iterate until the work lands or is explicitly closed. If you - can no longer pursue it, close the PR. Stalled PRs block progress. - -* **Do not use AI to claim "good first issue" tasks.** These issues exist to - help new contributors learn the codebase and processes hands-on. - -* **Edit generated comments critically.** LLM-produced comments are often - verbose or inaccurate. Remove comments that simply restate what the code - does; add comments only where the logic is non-obvious. - -## Using AI for communication - -Node.js values concise, precise communication that respects collaborator and contributor time. - -* **Do not post messages generated entirely by AI** in pull requests, issues, or the - project's communication channels. -* **Verify accuracy** of any LLM-generated content before including it in a - PR description or comment. -* **Link to primary sources** — code, documentation, specifications — rather - than quoting LLM answers or linking to LLM chats. -* Grammar and spell-check tools are acceptable when they improve clarity and - conciseness. - -[Developer's Certificate of Origin]: ../../CONTRIBUTING.md#developers-certificate-of-origin-11 -[OpenJS Foundation AI Coding Assistants Policy]: https://openjsf.cdn.prismic.io/openjsf/aca4d5GXnQHGZDiZ_OpenJS_AI_Coding_Assistants_Policy.pdf -[commit message guidelines]: ./pull-requests.md#commit-message-guidelines + +Pull requests that contain AI-generated code the contributor has not +personally understood, tested, and verified waste collaborator time and +will be subject to closure without additional review. Contributors who +repeatedly submit such changes, show no understanding of the project or +its processes, or are dishonest about the use of automated assistance +may be blocked from further contributions. + +Pull requests must not be opened by automated tooling, unless specifically +approved in advance by the project. To request approval, either open an issue in +[nodejs/admin](https://github.com/nodejs/admin/issues), or if the automation can +be done in the form of a GitHub workflow, submit a pull request to add the workflow +and use the usual pull request review process to seek consensus. + +## Using AI for code contributions + +Contributors may use AI tools to assist with contributions, but such tools +never replace human judgment. + +When using AI as a coding assistant: + +* **Understand the codebase first.** Do not skip familiarizing yourself with + the relevant subsystem. LLMs frequently produce inaccurate descriptions of + Node.js internals — always verify against the actual source. When using an AI + tool, ask it to cite the exact source it’s relying on, and then + match the claim against that resource to verify if it holds up in the current + code. + +* **Own every line you submit.** You are responsible for all code in your + pull request, regardless of how it was generated. This includes ensuring + that AI-generated or AI-assisted contributions satisfy the project's + [Developer's Certificate of Origin][] and licensing requirements. Be + prepared to explain any change in detail during review. + +* **Keep logical commits.** Structure commits coherently even when an LLM + generates multiple changes at once. Follow the existing + [commit message guidelines][]. + +* **Test thoroughly.** AI-generated code must pass the full test suite and + any manually written tests relevant to the change. Existing tests should not + be removed or modified without human verification. Do not rely on the LLM + to assess correctness. It is crucial to manually verify the correctness of + tests against the expected behavior of the feature being tested, + independently of the feature's implementation. + +* **Do not disappear.** If you open a PR, follow it through. Respond to + feedback and iterate until the work lands or is explicitly closed. If you + can no longer pursue it, close the PR. Stalled PRs block progress. + +* **Do not use AI to claim "good first issue" tasks.** These issues exist to + help new contributors learn the codebase and processes hands-on. + +* **Edit generated comments critically.** LLM-produced comments are often + verbose or inaccurate. Remove comments that simply restate what the code + does; add comments only where the logic is non-obvious. + +## Using AI for communication + +Node.js values concise, precise communication that respects collaborator and contributor time. + +* **Do not post messages generated entirely by AI** in pull requests, issues, or the + project's communication channels. +* **Verify accuracy** of any LLM-generated content before including it in a + PR description or comment. +* **Link to primary sources** — code, documentation, specifications — rather + than quoting LLM answers or linking to LLM chats. +* Grammar and spell-check tools are acceptable when they improve clarity and + conciseness. + +[Developer's Certificate of Origin]: ../../CONTRIBUTING.md#developers-certificate-of-origin-11 +[OpenJS Foundation AI Coding Assistants Policy]: https://openjsf.cdn.prismic.io/openjsf/aca4d5GXnQHGZDiZ_OpenJS_AI_Coding_Assistants_Policy.pdf +[commit message guidelines]: ./pull-requests.md#commit-message-guidelines