Repository navigation
CONTRIBUTING.md: add AI policy - #30782
Conversation
Yes, please! 💯 |
| If you're a non-native English speaker and are using an LLM to edit or translate | ||
| your comments, we recommend writing in your native language and including the | ||
| translation in a quote block. |
There was a problem hiding this comment.
I think this is a bit too strict. As a non native English speaker, I'll admit I use LLMs to help translate my comments these days. Previously, I relied on Google Translate or DeepL for specific words, and later moved on to Grammarly as my skills improved. Using an LLM makes the process much easier, even if the tone ends up a bit formal. :) Including my native language in a quote block is not what you want. 😶🌫️
There was a problem hiding this comment.
How would you rephrase this? The goal is to avoid generic too-wordy LLM lost-in-translation prose.
There was a problem hiding this comment.
I don't think it makes sense to encourage non-English posts as there's enough noise to navigate already.
If there's a genuine misunderstanding due to language barrier, a polite nudge is all it takes to get some clarification.
There was a problem hiding this comment.
@GeorgeSapkin I would suggest something like that: Using an LLM to translate or polish your comments is fine. Keep them short, review them before posting, and make sure they say what you mean.
| This policy was adapted from Astral's [AI Policy]( | ||
| https://github.com/astral-sh/.github/blob/c5187e200db51bfe11d56e13053d29bd3793fdd8/AI_POLICY.md). |
There was a problem hiding this comment.
These are very comprehensive. I tried to phrase the text as succinct as possible, considering people ignore what little guidelines there are at the moment.
|
I wonder if the policy should include that the only AI code review comments should be the ones by the (now terser) OpenWrt AI bot. I have found AI reviews by LLMs less strictly prompted to be concise are far too verbose (including raw Copilot). I have trialed some AI code reviewer, and until Hauke's recent terser update for OpenWrt AI, they've all been even wordier than I am, and that is not good. |
| We expect comments on our projects to be written by humans. The readers are | ||
| humans, and we'd like to hear from you, not from a model. We may hide or remove | ||
| any comments that we believe are LLM-generated. |
There was a problem hiding this comment.
The section just above (CONTRIBUTING.md:18-26) points contributors at the project's own automated LLM reviewer, which posts LLM-generated comments autonomously. This rule and the "no autonomous agents" one at line 43 read as covering it too. Should both say they apply to contributors, not to project-run review tooling?
Generated by Claude Code
There was a problem hiding this comment.
@openwrt-ai No worries. :) You're our friend, we like you, and your reviews are really helpful. 👍 We'll make an exception for you.
|
@GeorgeSapkin Many thanks for the initiative! One suggestion: The policy should specify how the involvement of LLMs in commits is to be indicated (e.g. by including the note ‘Assisted-by:’ or 'Co-authored-by:' at the end). Otherwise, everyone will do things differently. |
|
I agree with @dibdot as well, but I would love to see it in main repo, too! |
|
I was thinking of adding another checkbox to the PR template for voluntary LLM use disclosure on top of a commit trailer.
That's what I suggested adding a |
Not keen on this. It turns commit messages into a free unpaid advertising space for AI company brands, which is why Linux dropped the policy. If someone must have assistance from an LLM then so be it, but what matters is that it goes through the same vigorous human review as any other commit. (The harness that was used is probably more relevant than the underlying model, as that's what tends to determine what sources are used as reference and what procedures are followed. But again, this doesn't seem relevant for the commit log.) |
The kernel change is a proposed removal of the requirement, not merged yet, and the LKML thread is split. George’s PR template checkbox would be enough. My point is consistency, not attribution: reviewers benefit from knowing where to look, and right now everyone handles it differently. |
The checkbox idea makes perfect sense for GitHub interactions, bug reports, and PR discussions. Discussing a PR when the submitter appears to be non-human can feel demeaning. (Once or twice, I've continued such a discussion and it turned out to be productive, so I'm undecided whether it should be totally banned, but agree it should be disclosed and probably discouraged.) |
a02e5c9 to
7ee094c
Compare
|
@GeorgeSapkin Looks good to me, many thanks! |
openwrt-ai
left a comment
openwrt-ai
left a comment
There was a problem hiding this comment.
Commit checks
- 63e856a "CONTRIBUTING.md: add AI policy": the body leaves out the new mandatory LLM-usage disclosure rule (the WARNING block). Mention it in the body.
Generated by Claude Code
a2b1439 to
df7e24f
Compare
|
@danielfdickinson said:
That's my major complaint, too. PRs with a giant wall of text just piss me off and I skip them as I don't want to dig through a ton of noise to get to the actual content. Hauke's tuning of the openwrtAI reviews is really excellent, but the unconstrained submissions that we're seeing need to be gutted of all that flowery description that adds nothing (and in fact detracts from understandability). For me, that should be a major point in the policy itself. |
Wouldn't this just be a violation and thus closed? What would you phrase differently? The alternative is to write a comprehensive policy similar to other projects with separate sections for definitions, scope of policy, requirements, permitted and forbidden usage, disclosure, enforcement, etc. But I'm afraid even fewer people will bother with reading. |
I'd add a sentence to the "IMPORTANT" block, something like Keep posts concise and to-the-point: no "wall of text". |
Add a policy requiring human-written comments and contributions, with a human in the loop responsible for LLM-generated code. Signed-off-by: George Sapkin <george@sapk.in>
Hide comment sections from being displayed in the PR template. Add a helpful Markdown tip. Signed-off-by: George Sapkin <george@sapk.in>
Add a link to the AI policy and a LLM usage disclosure checkbox. Signed-off-by: George Sapkin <george@sapk.in>
df7e24f to
442fc17
Compare
This comment was marked as resolved.
This comment was marked as resolved.
Sorry, something went wrong.
@Ansuel, @hauke, @robimarko What do you think? Would that be suitable and something what main repo can consider? |
|
Thank you @GeorgeSapkin! |
| ## AI policy | ||
|
|
||
| > [!WARNING] | ||
| > You **must** disclose any LLM usage in your pull request, description or |
There was a problem hiding this comment.
FYI, the kernel merged similar guidelines for v7.0, and ~8 months later their removal was proposed: https://lore.kernel.org/lkml/20261009083137.3-1-sashal@kernel.org/
It's basically assumed that the majority of developers use LLMs these days. Shouldn't we rather steer the LLMs and make everyone's life easier? That likely means an AGENTS.md plus a few composable skills (openwrt-commit, openwrt-pull-request, openwrt-issue) that demand the appropriate content. Both are plain Markdown, so they work across harnesses (Codex, Copilot, Cursor, Gemini CLI, and Claude Code via a CLAUDE.md symlink).
To keep the human in the loop, AGENTS.md could tell the agent to add My human operator wasn't in the loop to every PR/issue body until the human explicitly approves it. If that line reaches GitHub, a check can label or auto-close the PR or issue.
There was a problem hiding this comment.
that demand the appropriate content
For example openwrt/openwrt#24500
- you need to provide proof to the reviewers, using for example x86/64 or armsr/armv8 QEMU VM, that the change was compile and e2e runtime tested using red-green TDD approach
- you need to provide flash/ram impact
- honestly report anything strange you bumped into in your sessions
...
Lets use the donated tokens in a way which works for this project.
There was a problem hiding this comment.
FYI, the kernel merged similar guidelines for v7.0, and ~8 months later their removal was proposed: https://lore.kernel.org/lkml/20261009083137.3-1-sashal@kernel.org/
This was already addressed. The proposed requirement here is different and relates to AI usage in the "pull request, description or commit messages" - in other words, you must disclose any AI usage in your GitHub messages and written prose in the commit message, via a checkbox.
The purpose is to discourage autonomous agents like Openclaw that open PRs and act on a user's behalf without operator guidance, which has been a growing problem in the OpenWrt repos. It is not related to the code or functional contents of the patch.
There was a problem hiding this comment.
The purpose is to discourage autonomous agents like Openclaw that open PRs and act on a user's behalf without operator guidance, which has been a growing problem in the OpenWrt repos.
Do those harnesses even read CONTRIBUTING.md? None load it automatically, only their own AGENTS.md/CLAUDE.md, and Claude Code was ignoring AGENTS.md until recently.
Checked OpenClaw (98bb32b): it doesn't read the target repo's CONTRIBUTING.md or PR template. Its gh skills open PRs with gh pr create --body-file and a hardcoded body, so the checkbox never shows up. If it delegates to Codex/Claude Code, those load the repo's AGENTS.md/CLAUDE.md.
So AGENTS.md (+ CLAUDE.md symlink) plus a CI check that fails when the disclosure is missing would probably catch them better.
There was a problem hiding this comment.
Checked OpenClaw (98bb32b): it doesn't read the target repo's CONTRIBUTING.md or PR template. Its gh skills open PRs with gh pr create --body-file and a hardcoded body, so the checkbox never shows up. If it delegates to Codex/Claude Code, those load the repo's AGENTS.md/CLAUDE.md.
Why does OpenWrt have to work around third-party tools' issues? And at which agent's, model's, harness's support do we draw the line? Why do we even need to enable drive-by contributions from people who neither read the basic guidelines, nor bother using the PR template?
There was a problem hiding this comment.
Checked OpenClaw (98bb32b): it doesn't read the target repo's CONTRIBUTING.md or PR template. Its gh skills open PRs with gh pr create --body-file and a hardcoded body, so the checkbox never shows up. If it delegates to Codex/Claude Code, those load the repo's AGENTS.md/CLAUDE.md.
Why does OpenWrt have to work around third-party tools' issues? And at which agent's, model's, harness's support do we draw the line?
@ynezz's finding is valuable. I wouldn't want to be the one to maintain a tangle of AGENTS files either, but let's hold on to that and revisit if the problem persists. There's some attraction to keeping the bots away via their own mechanism rather than banning them as they pop up - as a moderate contributor I don't have the ability to ban or even close spam PRs right now and I lose time every day because spam PRs remain open perpetually.
There was a problem hiding this comment.
Nit: The reference to OpenClaw doesn't work and points to openwrt/packages instead.
Honestly, seeing #30836 makes me just want to skip it without even reading it.
|
Continuing @ynezz thread, I also thought in AGENTS.md, I was following the qemu project approach time ago https://lists.nongnu.org/archive/html/qemu-devel/2026-05/msg03472.html and the recent proposal in the kernel https://www.phoronix.com/news/Linux-Considers-AGENTS-MD. I see the concerns about: minimize token consumption(getting less relevant?) vs extense guidelines. This is a quickly moving framework IMO there is a huge opportunity for always scarsed contributiors and, as we are seeing right now here, there are being huge contributions being done, for example, in the realtek and qualcommmax targets mainly pushed by agent based contributions.(Like ynezz noted too, Aren't these like donations for the project) The ugly part can be, for example, starting get used to good LLM and being a bit biased about others but hopefully, very soon, there are only good LLM anywhere. The AGENTS.md should help to these not top LLM to be much better. BTW, reading the AGENTS.md in the qemu project I felt like it should be called HUMANS.md to start with 😉🤖. The main doubt I have is how maintainers are going to integrate this in their workflows. A thing, I think, right now is doable and is missing, is automatic checks about related open PR, issues, mails or whatever which are forgotten and maintainers pushed the same or similar changes without noticing them. And how are maintainers to propose new contributors and how the newcomers are going to engage well enough in a mostly agent-based ecosystem... I mean, there used to be room for newcomers to start participating in easy tasks or simple reviews, now, that's mostly is gone with ai review and agent workflows. Being a good agent driver is enough? Long life for pre-IA maintainers! But I am not a maintainer so far, excuse my intrusion, thanks you all. Maintainers VS agents -> hybrid maintainers -> agent maintainers? 🤯 You did, such a wall text here... Sorry. |
|
@map-b I understood neither your point, nor how your comment relates to the topic at hand. On-going challenge in feeds since pre-LLM times has been the lack of maintainers and reviewers. Automated reviews are improving the quality of submissions – if contributors are not seagulls and bother to follow up – but they don't solve the lack of humans-in-the-loop who are going to sign-off and merge. Carpet-bombing projects with massive number of massive submissions is denial of service on human contributors that IMHO serves nobody. I have no incentive to review anything that has a whiff of LLM speak in it: if you can't be arsed to write it, I'm sure as hell won't be to review it. This is a for-fun volunteer-based project for me after all and I'd rather not argue with agents. There's no policy to guide my decisions one way or the other now, so I either ignore sus submissions altogether or close the most egregious examples at my discretion. Hence this PR. |
|
From the qemu mailing list I linked https://lists.nongnu.org/archive/html/qemu-devel/2026-09/msg09158.html +Motivation
+''''''''''
+
+There is not a consensus within the QEMU project---and likely never will
+be---about when/how/where it is acceptable to use AI-based tools. Many
+members of the QEMU project and community find value in AI; many others
+feel that its negative impact on society and the climate are severe enough
+that no use is acceptable. Still others are working out their opinion.
+
+In accordance with Software Freedom Conservancy's recommendations:
+
+- the project seeks to both support those contributors who outright reject
+ generative AI systems, and to not shun those who choose to use them;
+
+- we consider QEMU's copyleft to be a viable approach to the unanswered
+ legal questions about AI-generated contributions and their copyright
+ status;
+
+- we encourage contributors not to overuse LLMs, and to *add* them to
+ their existing skills and tools instead of replacing them.
+
+A common source of grief for maintainers is the (often valid) impression
+that AI enables contributions without understanding the effort they take
+for those who process them. Effectively, this shifts a major part of the
+burden from the contributors to the maintainers---the scarcest resource
+in any free software project, not just QEMU. Pre-arrangement and the
+size limit for small contributions try to avoid putting extra demand
+on maintainers due to LLM-assisted work.
+
+Sources
+'''''''
+
+This policy was informed by:
+
+- `Recommendations When Using LLM-backed Generative AI Systems for
+ FOSS Contributions
<https://sfconservancy.org/llm-gen-ai/llm-backed-generative-ai-recommendations.html>`__
+
+- `Rust project LLM Usage Policy
<https://forge.rust-lang.org/policies/llm-usage.html>`__
+
+- `GStreamer AGENTS.md file
<https://gitlab.freedesktop.org/gstreamer/gstreamer/-/blob/d08375499c279/AGENTS.md>`__
+I'm with you George, just I'm not sure we can put the exhausting genie back into the lamp. And any discussion in how to increase the number of maintainers would be lovely, even an agent backed maintainer for keeping the clearly agent based PRs in control , letting human maintainers be in peace. For example, if active(inactive aside) maintainers do not engage with new contributors, how are you suppose to get new maintainers? If a maintainer's side agent can help to create the routine and a little engagement, an "asynchronous" maintainer could get into the routine when he/she is really required or, simply, have the time for it, and by then, there would be some relationship and engagement to grow up. |
But removal what? I don't really think there's any conflict.
These rules are still present. And it's clearly, this PR is not against with AI assistants, it's against with AI slops. For most AI generated PR-s, I don't really think the so-called "contributors" can review the code they submit, and I don't even think they know what they are doing. Of course, you can optimize AI prompts, but you can't change people's understanding, and that sets the ceiling for AI. This is not a problem with the AI model's capabilities. For those PR-s, just like @BKPepe said, I have absolutely no interest in looking at them. If they're just going through the motions and don't even care about their own "work", why should maintainers waste time dealing with it? And why would anyone call these slop generators "contributors" in the first place? And why assume that new contributors are just people using AI to generate garbage? We're not against using AI for development. We're against using AI to produce garbage, and against people who don't clean up their own mess. That's exactly what this PR is saying. |
|
For now, I am merging this as it is. I like it. 👍 This is sitting here for a long time. |
Given the recent increase of LLM-generated contributions and comments 1, which leave maintainers reluctant to review PRs and to participate in further discussions, I propose adding a brief AI policy to the contributing guidelines. This policy requires human-written comments and contributions, with a human in the loop responsible for LLM-generated code, and discourages copy-pasting generated PR descriptions and comments.
Add a link to the AI policy and a LLM usage disclosure checkbox to the PR template.
Alternatively this could be in a separate policy file, or even a file in a top-level org-wide repo (i.e.,
.github2), if it's generic enough.This policy was adapted from Astral's AI Policy.
cc: @1715173329 @BKPepe @commodo @danielfdickinson @hnyman @stangri @wehagy
Footnotes
https://github.com/openwrt/packages/pull/30492#issuecomment-5644825977 ↩
https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/creating-a-default-community-health-file ↩