[PATCH] Documentation: document expectations around AI use

[PATCH] Documentation: document expectations around AI use

[Alyssa Ross]

It's been suggested to me a couple of times recently that having some
statement about AI use in contributions would be helpful, for a couple
of different reasons:

 • It resolves uncertainty contributors may feel about whether their
   AI-assisted contributions will be welcome, since there is a wide
   range of acceptance among open source software projects currently.

 • It teaches people submitting assisted contributions to avoid
   pitfalls that might reduce the success of their contributions
   without otherwise having been obvious to them.

 • It protects against precious reviewer time being spent trying to
   sift through verbose and confusing LLM-generated descriptions,
   which tends to be much less efficient for the reviewer.

I've tried to keep it as simple and minimally invasive as possible,
focusing on remedying specific problems that are likely to come up.
Each expectation has a brief explanation, because I expect people will
be happier following the guidance if they understand the reason for
it, but I've avoided going into too much detail to keep it easy to
read, understand and remember the whole thing.  There's some slight
deliberate ambiguity, because the important thing here is that people
follow the spirit of the expectations.  They don't need to get in the
way in situations where it would obviously make sense to do something
different; for example I can imagine certain situations where it
would be useful to share some LLM-generated prose.

Signed-off-by: Alyssa Ross <hi@alyssa.is>
---
We had a conversation about this on Matrix a little while ago, and I
hope this captures the consensus we had at the time.

I'm CCing everybody who's posted to the list recently (I think — sorry 
if I missed someone), because it's of course important to make sure
there's broad awareness of and agreement on the expectations.

I expect to apply this on top of my nav_order renumbering patch from
earlier, so this would show up in the documentation index after 
"Communication channels" and before "Sending Your Patch", since it's 
important context for people to have before sending their first patch.

 Documentation/doc/contributing/ai.adoc | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)
 create mode 100644 Documentation/doc/contributing/ai.adoc

diff --git a/Documentation/doc/contributing/ai.adoc b/Documentation/doc/contributing/ai.adoc
new file mode 100644
index 00000000..7535578e
--- /dev/null
+++ b/Documentation/doc/contributing/ai.adoc
@@ -0,0 +1,23 @@
+= Use of AI in Spectrum contributions
+:page-nav_order: 150
+
+// SPDX-FileCopyrightText: 2026 Alyssa Ross <hi@alyssa.is>
+// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
+
+Non-trivial Large Language Model (LLM) output in Spectrum contributions should
+be clearly marked as such.
+This is important context for reviewers, because humans and LLMs are prone to
+different kinds of mistakes.
+
+LLM-generated prose is discouraged.
+It tends to be overly verbose, and can be confusing because misunderstandings or
+false assumptions tend to be more difficult to spot in prose from LLMs than from
+humans.
+
+Contributors should ensure they understand and are able to answer questions about
+contributions they submit, in their own words.
+It's generally unhelpful to send LLM output in response to questions, because it
+can be expected that reviewers can ask LLMs questions themselves if LLM-generated
+answers would be useful to them.
+If a reviewer asks a contributor a question, it's because they want that
+contributor's answer, not an LLM's.

base-commit: 9dc81e02d6382ef7fc89b9bb246a71ff0fcc68ff
-- 
2.55.0

Re: [PATCH] Documentation: document expectations around AI use

[Demi Marie Obenour]

[-- Attachment #1.1: Type: text/plain, Size: 4029 bytes --]

On 8/4/26 12:41, Alyssa Ross wrote:
> It's been suggested to me a couple of times recently that having some
> statement about AI use in contributions would be helpful, for a couple
> of different reasons:
> 
>  • It resolves uncertainty contributors may feel about whether their
>    AI-assisted contributions will be welcome, since there is a wide
>    range of acceptance among open source software projects currently.
> 
>  • It teaches people submitting assisted contributions to avoid
>    pitfalls that might reduce the success of their contributions
>    without otherwise having been obvious to them.
> 
>  • It protects against precious reviewer time being spent trying to
>    sift through verbose and confusing LLM-generated descriptions,
>    which tends to be much less efficient for the reviewer.
> 
> I've tried to keep it as simple and minimally invasive as possible,
> focusing on remedying specific problems that are likely to come up.
> Each expectation has a brief explanation, because I expect people will
> be happier following the guidance if they understand the reason for
> it, but I've avoided going into too much detail to keep it easy to
> read, understand and remember the whole thing.  There's some slight
> deliberate ambiguity, because the important thing here is that people
> follow the spirit of the expectations.  They don't need to get in the
> way in situations where it would obviously make sense to do something
> different; for example I can imagine certain situations where it
> would be useful to share some LLM-generated prose.
> 
> Signed-off-by: Alyssa Ross <hi@alyssa.is>
> ---
> We had a conversation about this on Matrix a little while ago, and I
> hope this captures the consensus we had at the time.
> 
> I'm CCing everybody who's posted to the list recently (I think — sorry 
> if I missed someone), because it's of course important to make sure
> there's broad awareness of and agreement on the expectations.
> 
> I expect to apply this on top of my nav_order renumbering patch from
> earlier, so this would show up in the documentation index after 
> "Communication channels" and before "Sending Your Patch", since it's 
> important context for people to have before sending their first patch.
> 
>  Documentation/doc/contributing/ai.adoc | 23 +++++++++++++++++++++++
>  1 file changed, 23 insertions(+)
>  create mode 100644 Documentation/doc/contributing/ai.adoc
> 
> diff --git a/Documentation/doc/contributing/ai.adoc b/Documentation/doc/contributing/ai.adoc
> new file mode 100644
> index 00000000..7535578e
> --- /dev/null
> +++ b/Documentation/doc/contributing/ai.adoc
> @@ -0,0 +1,23 @@
> += Use of AI in Spectrum contributions
> +:page-nav_order: 150
> +
> +// SPDX-FileCopyrightText: 2026 Alyssa Ross <hi@alyssa.is>
> +// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
> +
> +Non-trivial Large Language Model (LLM) output in Spectrum contributions should
> +be clearly marked as such.
> +This is important context for reviewers, because humans and LLMs are prone to
> +different kinds of mistakes.
> +
> +LLM-generated prose is discouraged.
> +It tends to be overly verbose, and can be confusing because misunderstandings or
> +false assumptions tend to be more difficult to spot in prose from LLMs than from
> +humans.> +
> +Contributors should ensure they understand and are able to answer questions about
> +contributions they submit, in their own words.
> +It's generally unhelpful to send LLM output in response to questions, because it
> +can be expected that reviewers can ask LLMs questions themselves if LLM-generated
> +answers would be useful to them.
> +If a reviewer asks a contributor a question, it's because they want that
> +contributor's answer, not an LLM's.
> 
> base-commit: 9dc81e02d6382ef7fc89b9bb246a71ff0fcc68ff

What about LLM translation and LLM spelling/grammar checkers?
-- 
Sincerely,
Demi Marie Obenour (she/her/hers)

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [PATCH] Documentation: document expectations around AI use

[Valentin Gagarin]

I like the nature of the argument, but from my own experience would 
suggest a different policy: don't submit LLM output.

One piece of rationale behind that is in essence the same as yours, 
something along the lines of "contributors are assumed to understand 
what they're writing".  But even that still feels vague, because of 
course one can understand a given LLM output and package that as a 
contribution.  Therefore I would like to sharpen that line of reasoning 
before committing to that.

The other piece of rationale has more weight for me: you wouldn't submit 
search engine output verbatim either.  LLM output is qualitatively the 
same as generated code, plus randomness.  Why would you check that into 
version control?  That would also still need a constructive formulation 
for people further from this bubble to make sense immediately, but do 
you see what I'm getting at?

Certainly we should emphasize the part that sending LLM output 
needlessly shifts more burden onto reviewers, and the threshold to 
consider that spam is very easy to cross.

This deliberately leaves open which tools you use and how you use them 
to arrive at your contributions.  Another thing also worth mentioning is 
that the contributor may be liable for all the legal implications of 
labeling LLM output as one's own contribution.  What if a particular 
piece turns out to violate copyright?  For that reason, maintainers 
should therefore not let into their codebase what is marked as LLM 
output, and otherwise take authorship claims for granted.

But again, I agree with the spirit of your proposal, which to me reads 
like that the project's communication channels are for people, period. 
Still figuring out how to state it so that spirit gets across despite 
cultural differences.  Maybe this would even allow us to bypass the LLM 
debate in documentation altogether, ideally without having to re-explain 
why e.g. checking in any sort of machine output is not a good idea in 
general.

Thinking about it a bit more, the underlying theme is actually that of 
engineering, contribution, and communication culture.  It's easy to get 
along with people who happen to share it, but it's a lot of work for 
both sides when implicit assumptions don't match.  We may be even better 
served than by just policing LLM use if we state at least some of the 
core assumptions which drive the project, provide some guidance for how 
to soak up that culture, and ideally explicitly state positive examples. 
  That may substantially reduce the need to play catch-up with instances 
of the same phenomenon.

Re: [PATCH] Documentation: document expectations around AI use

[Alyssa Ross]

[-- Attachment #1: Type: text/plain, Size: 4872 bytes --]

On Tue, Aug 04, 2026 at 04:58:45PM -0400, Demi Marie Obenour wrote:
> On 8/4/26 12:41, Alyssa Ross wrote:
> > It's been suggested to me a couple of times recently that having some
> > statement about AI use in contributions would be helpful, for a couple
> > of different reasons:
> >
> >  • It resolves uncertainty contributors may feel about whether their
> >    AI-assisted contributions will be welcome, since there is a wide
> >    range of acceptance among open source software projects currently.
> >
> >  • It teaches people submitting assisted contributions to avoid
> >    pitfalls that might reduce the success of their contributions
> >    without otherwise having been obvious to them.
> >
> >  • It protects against precious reviewer time being spent trying to
> >    sift through verbose and confusing LLM-generated descriptions,
> >    which tends to be much less efficient for the reviewer.
> >
> > I've tried to keep it as simple and minimally invasive as possible,
> > focusing on remedying specific problems that are likely to come up.
> > Each expectation has a brief explanation, because I expect people will
> > be happier following the guidance if they understand the reason for
> > it, but I've avoided going into too much detail to keep it easy to
> > read, understand and remember the whole thing.  There's some slight
> > deliberate ambiguity, because the important thing here is that people
> > follow the spirit of the expectations.  They don't need to get in the
> > way in situations where it would obviously make sense to do something
> > different; for example I can imagine certain situations where it
> > would be useful to share some LLM-generated prose.
> >
> > Signed-off-by: Alyssa Ross <hi@alyssa.is>
> > ---
> > We had a conversation about this on Matrix a little while ago, and I
> > hope this captures the consensus we had at the time.
> >
> > I'm CCing everybody who's posted to the list recently (I think — sorry
> > if I missed someone), because it's of course important to make sure
> > there's broad awareness of and agreement on the expectations.
> >
> > I expect to apply this on top of my nav_order renumbering patch from
> > earlier, so this would show up in the documentation index after
> > "Communication channels" and before "Sending Your Patch", since it's
> > important context for people to have before sending their first patch.
> >
> >  Documentation/doc/contributing/ai.adoc | 23 +++++++++++++++++++++++
> >  1 file changed, 23 insertions(+)
> >  create mode 100644 Documentation/doc/contributing/ai.adoc
> >
> > diff --git a/Documentation/doc/contributing/ai.adoc b/Documentation/doc/contributing/ai.adoc
> > new file mode 100644
> > index 00000000..7535578e
> > --- /dev/null
> > +++ b/Documentation/doc/contributing/ai.adoc
> > @@ -0,0 +1,23 @@
> > += Use of AI in Spectrum contributions
> > +:page-nav_order: 150
> > +
> > +// SPDX-FileCopyrightText: 2026 Alyssa Ross <hi@alyssa.is>
> > +// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
> > +
> > +Non-trivial Large Language Model (LLM) output in Spectrum contributions should
> > +be clearly marked as such.
> > +This is important context for reviewers, because humans and LLMs are prone to
> > +different kinds of mistakes.
> > +
> > +LLM-generated prose is discouraged.
> > +It tends to be overly verbose, and can be confusing because misunderstandings or
> > +false assumptions tend to be more difficult to spot in prose from LLMs than from
> > +humans.> +
> > +Contributors should ensure they understand and are able to answer questions about
> > +contributions they submit, in their own words.
> > +It's generally unhelpful to send LLM output in response to questions, because it
> > +can be expected that reviewers can ask LLMs questions themselves if LLM-generated
> > +answers would be useful to them.
> > +If a reviewer asks a contributor a question, it's because they want that
> > +contributor's answer, not an LLM's.
> >
> > base-commit: 9dc81e02d6382ef7fc89b9bb246a71ff0fcc68ff
>
> What about LLM translation and LLM spelling/grammar checkers?

I think it would be difficult to argue that spelling/grammar checkers
are non-trivial LLM output or produce LLM-generated prose, no?

Translation I think is covered by "LLM-generated prose is discouraged."
It's not forbidden, so people can use it if they really need to, but
it's probably unhelpful in comparison to posting human generated text,
even if that's in another language.  That allows others who speak the
language to understand the original, and non-speakers without access to
a human speaker can use translation tools themselves, and with the
original text even have the option to use multiple if one tool produces
results that seem unclear or implausible.

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]