Skip to content

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.

Sign up for GitHub

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 6 commits into
base: main
Choose a base branch
from
+98 −0
Open

doc: create ai-guidelines and include to CONTRIBUTING #62105

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
8fa167d
doc: create ai-guidelines and include to CONTRIBUTING
RafaelGSS Mar 4, 2026
cee1884
Apply suggestions from code review
RafaelGSS Mar 5, 2026
483c41b
Apply suggestions from code review
RafaelGSS Mar 13, 2026
8944958
fixup! Apply suggestions from code review
RafaelGSS Mar 13, 2026
9168e27
fixup! fixup! Apply suggestions from code review
RafaelGSS Apr 1, 2026
c9e7c08
fixup! fixup! fixup! Apply suggestions from code review
RafaelGSS Apr 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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
Copy link
Copy Markdown
Contributor

@bmuenzenmeyer bmuenzenmeyer Mar 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this first sentence seems intentionally to be the same as the full policy document, which now has a suggested change. marking this here to resolve whether or not the language should continue syncing, if it should change

every change they propose. Pull requests consisting of AI-generated code the
contributor has not personally understood, tested, and verified will be closed
Comment thread
RafaelGSS marked this conversation as resolved.
Outdated
without review.
Comment thread
RafaelGSS marked this conversation as resolved.
Outdated
Comment on lines +54 to +56
Copy link
Copy Markdown
Member

@tniessen tniessen Apr 15, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
every change they propose. Pull requests consisting of AI-generated code the
contributor has not personally understood, tested, and verified will likely be closed
without review.
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
Expand Down
57 changes: 57 additions & 0 deletions doc/contributing/ai-guidelines.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Comment thread
jasnell marked this conversation as resolved.
Outdated
every change they propose. The answer to "Why is X an improvement?" should
Comment thread
jasnell marked this conversation as resolved.
Outdated
never be "I'm not sure. The AI did it."

Pull requests that consist of AI-generated code the contributor has not
Copy link
Copy Markdown
Member

@tniessen tniessen Apr 15, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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 closed without review.
Comment thread
RafaelGSS marked this conversation as resolved.
Outdated

## Using AI for code contributions

AI tools may assist contributors, but must not replace contributor judgment.
Copy link
Copy Markdown
Member

@avivkeller avivkeller Mar 19, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
AI tools may assist contributors, but must not replace contributor judgment.
AI tools may assist contributors, but must not replace human judgment.

When using AI as a coding assistant:
Comment thread
jasnell marked this conversation as resolved.
Outdated

* **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.
Comment thread
RafaelGSS marked this conversation as resolved.
Outdated

* **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.
Copy link
Copy Markdown
Member

@jasnell jasnell Mar 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* **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.
* **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.

(would need a DCO link added at the bottom of the page also)


* **Keep logical commits.** Structure commits coherently even when an LLM
generates multiple changes at once. Follow the existing
[commit message guidelines][].
Comment thread
RafaelGSS marked this conversation as resolved.

* **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
Comment thread
RafaelGSS marked this conversation as resolved.
Outdated
to assess correctness.
Comment on lines +57 to +60
Copy link
Copy Markdown
Member

@tniessen tniessen Apr 15, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Some hallucination machines may write tests based on the implementation of a feature instead of considering the expected behavior of the feature.

Suggested change
* **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.
* **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.

Copy link
Copy Markdown
Member

@ChALkeR ChALkeR Apr 20, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we extract this and also apply to human-written code too? (but keep it here also)

I believe we have existing decade-old tests that should be subject to this

Mostly "increase coverage" PRs are highly subject to documenting bugs instead of fixing them (not just in Node.js, but overall)


* **Edit generated comments critically.** LLM-produced comments are often
Copy link
Copy Markdown
Contributor

@italojs italojs Mar 19, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.
Comment thread
RafaelGSS marked this conversation as resolved.

## Using AI for communication

Node.js values concise, precise communication that respects collaborator time.
Copy link
Copy Markdown
Member

@avivkeller avivkeller Mar 19, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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 AI-generated messages** in pull requests, issues, or the
project's communication channels.
Comment thread
RafaelGSS marked this conversation as resolved.
Outdated
Copy link
Copy Markdown
Member

@jasnell jasnell Mar 19, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Member

@ljharb ljharb Mar 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's only difficult to enforce if it's low quality prose, though, in which case this item seems like it'd be needed.

Copy link
Copy Markdown
Contributor

@bmuenzenmeyer bmuenzenmeyer Mar 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this also disenfranchises people that use an AI to help them write English, as it might not be their first language

Copy link
Copy Markdown
Member

@ljharb ljharb Apr 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).

Copy link
Copy Markdown
Member

@jasnell jasnell Apr 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Member

@ljharb ljharb Apr 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The point of a policy like this is to decide for them what tools they're allowed to use, even if that decision is "all of them". It's perfectly reasonable to tell people not to perform translations themselves, so that their intent is not lost (as it otherwise could be)

Copy link
Copy Markdown
Member

@ChALkeR ChALkeR Apr 20, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's only difficult to enforce if it's low quality prose, though, in which case this item seems like it'd be needed.

Creating incentives to breaking the rules in letter and assuming that those rules in letter would be broken is a bad policy (and means that the rule is formulated incorrectly)

It should be rephrased in a way that would allow high-effort/reviewed comments even if primarly generated by LLM, but disallow unreviewed/low-quality ones.

* **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.
Copy link
Copy Markdown
Member

@mcollina mcollina Mar 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we have a template? I thought those are for issues, not PRs.

Copy link
Copy Markdown
Member

@legendecas legendecas Mar 5, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not strictly a template: https://github.com/nodejs/node/blob/main/.github/PULL_REQUEST_TEMPLATE.md?plain=1

Copy link
Copy Markdown
Contributor

@MikeMcC399 MikeMcC399 Mar 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's not possible to fulfil the instructions "Complete pull request templates fully" based on the contents of https://github.com/nodejs/node/blob/main/.github/PULL_REQUEST_TEMPLATE.md?plain=1 so it looks like this sentence needs to be removed.

Copy link
Copy Markdown
Member

@mcollina mcollina Mar 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* **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.
* **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.
Copy link
Copy Markdown
Member

@avivkeller avivkeller Mar 19, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* **Link to primary sources** — code, documentation, specifications — rather
than quoting LLM answers.
* **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.

[commit message guidelines]: ./pull-requests.md#commit-message-guidelines
Loading