doc: create ai-guidelines and include to CONTRIBUTING #62105
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,88 @@ | ||
| # 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, that should be | ||
| acknowledged honestly (e.g., via an `Assisted-by:` tag in the commit | ||
| metadata) so that reviewers have appropriate context. | ||
|
Member
There was a problem hiding this comment. Personally I find some of the tool mentions in PRs these days already somewhat annoying, it's like "sent from my iPhone" advertisements everywhere and more marketing in the commit logs. Especially when issues are found and the explanation is just "this (proprietary) AI tool did it/made me believe it", as if the tool is an excuse because it's supposed to be the best. I think if people let the tools do most of the work that it requires reviewer's awareness, it's much better to include your prompt and roughly explain your process than just leaving what (likely proprietary) model and tool you use. Also the list can be very long if they use multiple tools and it's just more advertisement/marketing noise.
Member
There was a problem hiding this comment. Including the prompt is impractical in most cases. For example, in the PRs where I use AI assistance the "prompt" is typically a multi-session chat with many prompts. I don't consider the prompts really to be all that useful.
Member
There was a problem hiding this comment. I don't think it needs to be the exact same prompt, but if we are talking about usefulness, "here's the process of how I used the tools to come to this diff" is much more useful and relevant to determine the soundness of the diff than "I used this specific model and this specific tool" but without any description of how it arrives at that diff. If the process is sound, you could probably arrive at the same diff with just any tool/model or no AI at all with varying level of efficiency, but mentioning one specific tool/model just feels like marketing if we don't care about "how long it takes to arrive at this diff", only "the quality of this diff". Even pre-AI, I don't think people would say "I use IntelliJ IDEA to refactor these names in the code base" in the commit logs, they just describe the refactoring rules and motivations in the logs. If the process is not sound, there's little difference in what model/tool/human you use to arrive at that diff. |
||
|
|
||
| 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. 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][]. | ||
RafaelGSS marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| * **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. | ||
|
|
||
| * **Do not disappear.** If you open a PR, follow it through. Respond to | ||
|
Contributor
There was a problem hiding this comment. What is / can we link to our official policy on "stale" or stalled PRs? Like regardless if its involving AI do we have a policy to close out PRs after a certain amount of time? If not, should we?
Member
There was a problem hiding this comment. Right now our automation closes PRs if they are both older than a year and have had no activity in the past sixth months, but IMO we should make that just six months (no year clause) |
||
| 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 | ||
|
Contributor
There was a problem hiding this comment. I would recommend adding an extra rule to not push "linter" changes that LLM usually does, it's pretty frequent at meteor, and dirty the commits and PR history |
||
| verbose or inaccurate. Remove comments that simply restate what the code | ||
| does; add comments only where the logic is non-obvious. | ||
RafaelGSS marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| ## 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. | ||
|
Member
There was a problem hiding this comment. I'm less convinced this one is necessary. It's also difficult to enforce. These should follow the same rules as contributions... whatever is posted, you're responsible for, so use appropriate discretion.
Member
There was a problem hiding this comment. It's only difficult to enforce if it's low quality prose, though, in which case this item seems like it'd be needed.
Contributor
There was a problem hiding this comment. I think this also disenfranchises people that use an AI to help them write English, as it might not be their first language
Member
There was a problem hiding this comment. They shouldn't be doing that, though - they should just write in their native language and the reader can use AI and/or translation tools. I'd always much rather read broken English than a mistranslation (which are frequent).
Member
There was a problem hiding this comment. We can all have opinions about what others should or should not do and about what we personally prefer to see, but we should let people decide for themselves what tools they want to use and why. |
||
| * **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 | ||
| [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 | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This should be expanded a bit, see https://docs.kernel.org/process/coding-assistants.html#attribution., I would just drop the tools, so: