-
-
Notifications
You must be signed in to change notification settings - Fork 36.4k
doc: create ai-guidelines and include to CONTRIBUTING #62105
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
RafaelGSS
wants to merge
2
commits into
nodejs:main
Choose a base branch
from
RafaelGSS:add-ai-guidelines
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
+108
−0
Open
Changes from all commits
Commits
Show all changes
2 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Some comments aren't visible on the classic Files Changed page.
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,98 @@ | ||
| # AI use policy and guidelines | ||
|
|
||
| * [Core principle](#core-principle) | ||
| * [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 | ||
|
|
||
| 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 | ||
| 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. | ||
|
|
||
| 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 | ||
| `<brand>`), 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 | ||
| 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. | ||
|
|
||
| ## When AI is used in 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. 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 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 | ||
| 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. | ||
|
|
||
| * **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. | ||
|
|
||
| ## When AI is used in communications | ||
|
|
||
| Node.js values concise, precise communication that respects collaborator and | ||
| contributor time. | ||
|
|
||
| * **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 | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.
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.
I was just reading a post by a maintainer of another prominent OSS project today who was frustrated by a 10K+ LOC AI-generated PR and saw some wording about this behavior that we can borrow - I also saw this behavior when reviewing #63115 which exposed
internalModuleStatby mistake and then went on to make even more mistakes by ensuring the internal API is publicly usable 🤦🏻♀️, seems like a common issue of AI-generated big patches