From 2c97efda1e35cf2eafa6e85969fe1e8950459c1a Mon Sep 17 00:00:00 2001 From: RafaelGSS Date: Thu, 28 May 2026 17:04:16 -0300 Subject: [PATCH 1/2] doc: create ai-guidelines and include to CONTRIBUTING MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Beth Griggs Co-authored-by: Aditi <62544124+Aditi-1400@users.noreply.github.com> Co-authored-by: Joyee Cheung 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 Co-authored-by: James M Snell Co-authored-by: Trivikram Kamat <16024985+trivikr@users.noreply.github.com> Signed-off-by: RafaelGSS --- CONTRIBUTING.md | 10 +++ doc/contributing/ai-guidelines.md | 101 ++++++++++++++++++++++++++++++ 2 files changed, 111 insertions(+) create mode 100644 doc/contributing/ai-guidelines.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 54296234a304..dcf14866e745 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 requires contributors to understand and take full responsibility for +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. + +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 000000000000..81f1d9a45d7b --- /dev/null +++ b/doc/contributing/ai-guidelines.md @@ -0,0 +1,101 @@ +# 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. + +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 codebase, from being +abused for profit-driven 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, 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-generated 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 From 2d778890bbd7647e40f3b60b24b46350439c3396 Mon Sep 17 00:00:00 2001 From: RafaelGSS Date: Wed, 5 Aug 2026 15:55:12 -0300 Subject: [PATCH 2/2] fixup! doc: create ai-guidelines and include to CONTRIBUTING Signed-off-by: RafaelGSS --- doc/contributing/ai-guidelines.md | 89 +++++++++++++++---------------- 1 file changed, 43 insertions(+), 46 deletions(-) diff --git a/doc/contributing/ai-guidelines.md b/doc/contributing/ai-guidelines.md index 81f1d9a45d7b..16634f3add11 100644 --- a/doc/contributing/ai-guidelines.md +++ b/doc/contributing/ai-guidelines.md @@ -1,16 +1,15 @@ # 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) +* [When AI is used in contributions](#when-ai-is-used-in-contributions) +* [When AI is used in communications](#when-ai-is-used-in-communications) 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. +Tools should never replace human judgment, regardless of whether they are +powered by AI. Node.js requires contributors to understand and take full responsibility for every change they propose. The answer to "Why is X an improvement?" can @@ -20,13 +19,15 @@ 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 codebase, from being -abused for profit-driven marketing. +Be aware that the mention of for-profit trademarks or commercial brands in +commit messages, which are part of the code base, can be abused for +profit-driven marketing. If the disclosure involves for-profit trademarks or +commercial brands, it's recommended to either anonymize the branding (e.g. say +`a frontier reasoning model`, `a closed-source coding agent` instead of +``), or only mention the for-profit brand/trademark in the PR +description, but not in the commit message, unless the message would not have +made sense without mentioning the specific brand/trademark. These +recommendations only apply to for-profit tools/models, not any non-profit ones. Pull requests that contain AI-generated code the contributor has not personally understood, tested, and verified waste collaborator time and @@ -38,10 +39,10 @@ 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. +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 +## When AI is used in contributions Contributors may use AI tools to assist with contributions, but such tools never replace human judgment. @@ -49,28 +50,22 @@ 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. + the relevant subsystem. Always verify analysis generated by tools against + the actual source code with human judgement. * **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. + pull request, regardless of how it was created. The submitted changes + must satisfy the project's [Developer's Certificate of Origin][] and licensing + requirements. Be prepared to explain any change in detail during review. + +* **Keep the commits logical.** The [commit message guidelines][] + and [commit squashing guidelines](./pull-requests.md#commit-squashing) + must be followed regardless of what tool is used in the pull request. + +* **Test thoroughly.** Existing tests should not be removed or modified + without human verification. It is crucial to verify, with human judgement, + the correctness of new 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 @@ -79,23 +74,25 @@ When using AI as a coding assistant: * **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-generated comments are often - verbose or inaccurate. Remove comments that simply restate what the code - does; add comments only where the logic is non-obvious. +* **Keep the comments useful.** Verify with human judgement that the + comments are necessary and accurate. Remove comments that simply + restate what the code does. Add comments only where the logic is non-obvious. -## Using AI for communication +## When AI is used in communications -Node.js values concise, precise communication that respects collaborator and contributor 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. -* **Link to primary sources** — code, documentation, specifications — rather - than quoting LLM answers or linking to LLM chats. +* **Do not paste messages generated entirely by AI** in pull requests, issues, + or the project's communication channels. Such communication may be removed in + accordance to [the Node.js moderation policy][]. +* **Verify claims about the code with human judgement before using them in + communications**. Results from AI tools should only be treated as hypothesis. + Link to actual code, documentation and specifications as source of truth. * 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 +[the Node.js moderation policy]: https://github.com/nodejs/admin/blob/main/Moderation-Policy.md