Guidelines for AI-Assisted Contributions in the ROS Project

ROS ROS General
, , , ,
1

Hello fellow ROS users, maintainers, contributors and anyone else who may be passing by.

Due to a recent uptick in LLM-authored pull requests, the ROS PMC has elected to extend the upstream OSRF policy on the use of generative tools to help provide some boundaries/guidelines on the use of these tools. These tools and technologies are constantly changing, so this isn’t intended to serve as a permanent policy, but rather it is to provide a framework for how to interact on ROS-related projects.

The TLDR, because there are a lot of words below: Feel free to use the tools to build, explore, and understand software (as many of the maintainers also do), but when it comes time to interact on Discourse, Zulip, or Github, try to leave the LLM-centric text behind. A large component of open source software is about building/collaborating with people, and we would generally prefer to interact with people rather than an LLM-proxy.

Maintainer time is a finite and constrained resource. While generative AI tools can be useful development assistants, submitting unverified Large Language Model (LLM) output shifts the engineering, debugging, and verification work onto project maintainers.

This document establishes the rules for interacting with ROS project repositories when using AI tools. It serves as an extension of the upstream OSRF Policy on the Use of Generative Tools in Contributions. While the upstream policy defines the legal, IP, and attribution requirements for AI-generated code, these rules define the quality and behavioral standards required to protect maintainer bandwidth.

The Author Ownership Rule

The upstream OSRF policy states that contributors must have the right to sign the Developer Certificate of Origin (DCO). Operationally, this means you are the sole owner of, and are fully responsible for, the code you submit.

  • Do not use maintainers as an LLM validation service. If a maintainer points out a bug, architectural issue, or syntax error in your PR, you may not simply paste that feedback back into an LLM and copy-paste the unverified output as a response.

  • You must understand every line of code you submit. If a maintainer asks why a specific technical choice was made, responding with “an LLM generated this” or providing a generic, AI-synthesized explanation is unacceptable. You must be able to defend the technical merits of your implementation yourself.

  • Maintainers want to engage with you, the author of the proposed changes. Maintainers want to understand why you want to make the change and why you want to implement it the way the PR proposes. Maintainers do not want to talk to your chatbot.

Zero-Tolerance for Hallucinated API/Dependency Usage

LLMs frequently hallucinate APIs, configuration parameters, or entire library features, especially given the fast-moving nature of ROS releases and underlying middleware (DDS, Zenoh, rclcpp, rclpy, etc.).

  • Any PR that introduces non-existent APIs, impossible configuration keys, or broken logic due to LLM hallucinations will be closed immediately without review.

  • Repeat offenses will result in a temporary or permanent block from the organization’s repositories.

Compliance with Upstream Disclosure & Attribution

The upstream OSRF policy explicitly requires that the use of generative tools be disclosed if they created a material part of the contribution. We enforce this strictly on GitHub:

  • If an LLM was used to generate structural code, tests, or documentation boilerplate, state it clearly in the PR description.

  • Do not LLM dump to generate your PR description. Paragraphs filled with generic AI phrasing (e.g., “This PR enhances the efficiency of the codebase by utilizing modern design patterns and optimizing asynchronous paradigms…”) will be rejected. Write a concise, human-authored summary explaining exactly what changed and why.

Enforcement and Maintainer Recourse

To maintain the health of the project, maintainers have full discretion to handle low-effort, AI-driven contributions efficiently:

  • If an issue or PR is clearly an unverified LLM dump (e.g., containing generic AI comments, formatting that violates project style guides, contains a poorly formatted description pasted directly from an LLM, or obviously broken logic), maintainers are authorized to close the PR immediately.

  • If a contributor responds to code review feedback using obvious, unedited LLM-generated text that fails to address the underlying engineering critique, maintainers are authorized to close the PR immediately.

  • If the contributor fails to respond to reviewer questions or feedback within a reasonable timeframe (e.g. within a week), reviewers may close the PR without further review.

  • If a contributor continues to behave in an unproductive way through repeated submission of inappropriate LLM-dump issues or PRs, repeated copy-and-pasting of LLM-dump comments, or similar, maintainers are authorized to temporarily or permanently block that user from the organization’s repositories.

Guidelines for Responsible AI Use in ROS

If you want to use an LLM to help you successfully contribute to ROS, adhere to the following workflow:

  1. Confirm that the issue is still valid and that any proposed solution is still preferred. Start a conversation on the issue thread to ensure maintainers agree with the approach. Opening PRs for stale or invalid issues simply because an AI bot identified them creates unnecessary overhead for maintainers and is strongly discouraged.

  2. Run the code locally. Verify it compiles, passes linting, and passes all relevant tests before opening a PR.

  3. Before hitting “Submit,” read through your own diff line-by-line. Remove any redundant logic, overly verbose AI-generated comments, or structural weirdness introduced by the model.

  4. Explain your changes in plain technical language. If you can’t describe the change yourself, you aren’t ready to submit it.

45 Likes
Gazebo PMC Meeting Minutes 2026-07-06
ROS News for the Week of July 6th, 2026
2

Additionally, we are looking at rolling out AGENTS.md across many of our repos to hopefully make our LLM-assistants respect these guidelines. I would be interested to hear from anyone who has experience keeping the agents in line.

5 Likes
3

Are there also some guidelines on the usage of LLMs by maintainers?

4

I would say that generally, the same rules apply. I know many people use them, but I would expect that interactions on issue trackers, pull requests, etc are done by the author.

I know that I have been guilty of being a little excited about automation in the past, but I think for long-term health, we should mostly be interacting as humans.

That being said, I personally don’t mind getting a human-authored summary/conversation and also the LLM output, as it’s often helpful context but easily ignored. The spirit of the guidelines here are more that we shouldn’t just be LLM dumping on each other constantly because everyone (maintainers and contributors) will just run out of bandwidth.

5 Likes
5

I very much agree with this policy and has been what I’ve started to adhoc do in Nav2 over the last couple of weeks independently. The number of sloppy AI PRs and issues (often addressing nonsensical issues) is getting too exhausting to address in a thoughtful process-oriented way. I hit a point of almost complete burn-out by dozens of nonsense ‘security’ reports or massive rewrites generated by AI with either no follow-up or excessive and/or incorrect AI generated follow-up to a point I was dreading opening GitHub in the morning.

I’m happy to see someone put in better words and will align with this for Nav2 as well. This type of action has saved my sanity.

10 Likes
6

You are absolutely right to push back on LLM use for human-centric conversations!

(sorry, couldn’t resist). I think this is a right move. I find it so tiring to read AI slop these days that when I see a typical LLM-like structures in text, I just give up. Are you going to add anything to Discord onboarding flow to ask people to not use LLMs?

2 Likes
7

Tom Fishburne has a visual way to explain the problems that I find very relevant

image
image1200×628 164 KB

More at AI Written, AI Read cartoon - Marketoonist | Tom Fishburne

And long live human interactions!

14 Likes
8

Off-topic: I’m all for (human-crafted) single bullet point emails :slight_smile:

3 Likes
9

I would honestly caution against this
at most, these guidelines should be present in a CONTRIBUTING.md
if the person using the LLM is not capable of reading that and complying with it, then their PR can simply be ignored.

anyone serious about contributing will read it, and if they haven’t read it, they are not serious about contributing

further, the presence of AGENTS.md, CLAUDE.md, etc. files really turns me off from contributing to any project I see.
for some time now, I’ve been wanting to contribute more to ROS, however something like this would make me less likely to

1 Like
10

Out of curiosity: why? I would think out of stigma of the project being fully AI generated, but with known quality and reliably maintained projects, why would this steer you away?

11

Hi mjcarroll,

Thanks for putting this together — this is a much-needed framework. As someone who’s been building an open-source agent system (ClawsJoy) that involves LLM-based orchestration, I’ve been thinking about this exact tension: AI tools accelerate exploration, but the human element is what makes open source sustainable.

A few thoughts from the perspective of an active LLM tool user and project maintainer:

1. The “understand what you’re submitting” rule is the most important one. This is what separates using AI as a pair programmer vs using it as a delegation machine. I’ve adopted the practice of writing the explanation first (in plain human language, describing what I want to change and why), then using AI to assist with implementation, then reviewing the diff line by line before submitting. The explanation stays in the PR description — it’s the human-authored “contract” that the code needs to satisfy.

2. One challenge I haven’t seen fully addressed: verifying that AI-generated code actually works in the specific ROS environment. LLMs are often trained on generic ROS 2 examples, but real-world usage involves specific distros, middleware versions (DDS, Zenoh), and hardware. I’ve found that the biggest time sink isn’t generating code — it’s validating that the generated code is compatible with the actual environment. Would love to see community-shared validation workflows (e.g., a CI check that flags potential API mismatches).

3. On disclosure formatting: The commit-message Generated-by: approach makes sense for traceability. One thing I’m experimenting with is a GENERATED-BY: comment in the source file itself for structural code sections (e.g., “this entire class was generated by X”), and commit-message disclosure for smaller snippets. Happy to share what works/doesn’t as I learn.

4. From a maintainer’s perspective: The hardest part isn’t detecting LLM-generated code — it’s detecting LLM-generated code that looks plausible but is subtly wrong. The guidelines on hallucinated API usage and zero-tolerance for unverified output are spot on. I’d add: if an LLM-generated PR passes the “read your own diff” test (i.e., the author can explain every line), that’s already a strong signal that the author has done the necessary work.

One quick question: For projects that are already heavy users of AI tools, are you considering any tooling to automate the disclosure tracking? E.g., a pre-commit hook that prompts for a disclosure statement when it detects certain patterns, or a CI check that validates commit message format? This could reduce the friction of compliance and make it easier for contributors to “do the right thing” without extra mental overhead.

Again, appreciate the thought put into this. It sets a healthy tone for the community as these tools become more integrated into everyday development.

ClawsJoy — building open-source agent infrastructure for robotics and beyond. Happy to connect if any of this is useful, or if you’d like to see how we’re approaching these challenges in a different domain.

13

These guidelines are specifically for contributing to the repositories managed by the OSRA. Verifying that AI-generated code works is the same as verifying that human-produced code works.

For other ROS code maintained by others (e.g. Nav2, or a package produced by a company building a product on ROS), they can and will decide their own policies.

The OSRA policy recommends Assisted-by commit statements and comments, as it more closely fits how we want people to use these tools: as assistants, not replacements for themselves.

1 Like
14

I totally support this. It is also a point of my research on the impact of AI in ROS software development and communities. Does anyone is willing to take part of it? Let me know.

15

This is really solid! Might start referring to this for the NASA-JPL Open-Source Rover where we’ve been getting a few clearly AI generated PRs

16

If non-OSRA ROS projects want to adopt this policy, can we just link it from our CONTRIBUTING.md?

17

You can, but we may change it at any time, so it’s probably better to copy it yourself unless you are OK with it suddenly changing.

1 Like