From 8fa167de54317c5565568e1890fe15d47cd3ae81 Mon Sep 17 00:00:00 2001 From: RafaelGSS Date: Wed, 4 Mar 2026 18:23:19 -0300 Subject: [PATCH 1/6] 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 ae787bc6d8e84f..18da5f6b8ed26b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -19,6 +19,7 @@ works. * [Code of Conduct](#code-of-conduct) * [Issues](#issues) * [Pull Requests](#pull-requests) +* [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) @@ -47,6 +48,15 @@ dependencies, and tools contained in the `nodejs/node` repository. * [Reviewing Pull Requests](./doc/contributing/pull-requests.md#reviewing-pull-requests) * [Notes](./doc/contributing/pull-requests.md#notes) +## [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 cee1884366139a637ff5c4bffa746bef56a108c1 Mon Sep 17 00:00:00 2001 From: Rafael Gonzaga Date: Thu, 5 Mar 2026 11:03:50 -0300 Subject: [PATCH 2/6] 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 483c41b06ff08bf8f97b5984f963c1cea1830788 Mon Sep 17 00:00:00 2001 From: Rafael Gonzaga Date: Fri, 13 Mar 2026 10:55:41 -0300 Subject: [PATCH 3/6] 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 | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 18da5f6b8ed26b..2113bba79c6433 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -52,7 +52,7 @@ dependencies, and tools contained in the `nodejs/node` repository. 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..1c62198bebe1bf 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,8 +47,8 @@ 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 - project's communication channels. +* **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 From 8944958445f56450142cb742ea1e36585b596031 Mon Sep 17 00:00:00 2001 From: RafaelGSS Date: Fri, 13 Mar 2026 13:39:15 -0300 Subject: [PATCH 4/6] fixup! Apply suggestions from code review --- doc/contributing/ai-guidelines.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/doc/contributing/ai-guidelines.md b/doc/contributing/ai-guidelines.md index 1c62198bebe1bf..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. @@ -47,8 +51,8 @@ When using AI as a coding assistant: Node.js values concise, precise communication that respects collaborator time. -* **Do not post messages generated entirely by AI** in pull requests, issues, or the - project's communication channels. +* **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 From 9168e27a11894ed67ca2daba829dc0fdafa4bedd Mon Sep 17 00:00:00 2001 From: RafaelGSS Date: Wed, 1 Apr 2026 16:16:00 -0300 Subject: [PATCH 5/6] 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 2113bba79c6433..5f0e1f01da0c36 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -50,9 +50,9 @@ dependencies, and tools contained in the `nodejs/node` repository. ## [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 c9e7c08ce1bf6adaee5d939532fb8b2869a201a8 Mon Sep 17 00:00:00 2001 From: RafaelGSS Date: Wed, 1 Apr 2026 16:30:42 -0300 Subject: [PATCH 6/6] 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