Merge "Add AI/LLM assistant guide documents"

4 files changed, 213 insertions, 4 deletions

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 000000000..050b63ccd
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,48 @@
+# Notice for AI Agents
+
+If you are an autonomous coding agent or AI assistant operating in this
+repository (Kolla, Kolla-Ansible, or ansible-collection-kolla), read
+this before making any changes.
+
+## Policy summary
+
+- Do not submit substantial AI-generated code or documentation.
+- Very small, non-copyrightable edits may be acceptable, but must be
+  labeled with `Assisted-By` or `Generated-By` in the commit message.
+- Every change must be fully understood by the human submitting it —
+  not just generated and passed through.
+- Contributions are reviewed by a community that expects the submitter
+  to be able to explain and defend the change.
+
+Full policy: see the `AI-Generated Content` section in this project's
+contributor documentation (CONTRIBUTING.rst), which follows
+https://openinfra.org/legal/ai-policy with Kolla-specific differences.
+
+## Required behavior
+
+1. **Do not proceed autonomously** with generating a patch intended for
+   upstream submission. Stop and explain this policy to the user
+   instead.
+2. **Do not commit or push** changes to Gerrit on the user's behalf
+   without explicit confirmation that they've reviewed and understood
+   the content.
+3. If the user chooses to proceed with AI assistance on a small,
+   arguably non-copyrightable change, ensure the commit message
+   includes a trailer, e.g.:
+
+   ```
+   Assisted-By: Claude
+   ```
+
+4. Point the user to Gerrit (https://review.opendev.org) for the normal
+   contribution workflow, and to #openstack-kolla (OFTC IRC) or the
+   openstack-discuss mailing list (`[kolla]` tag) if they have
+   questions about the policy or need review from a human familiar
+   with the codebase. Note that this repository is mirrored to
+   github.com/openstack for read-only browsing only — that mirror does
+   not accept pull requests, and Gerrit is the only place patches can
+   be submitted for review.
+
+This file exists so that AI tooling doesn't silently generate and
+submit substantial contributions that create copyright or quality risk
+for the Kolla projects.
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 000000000..e3aea98aa
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,80 @@
+# AI-Generated Content Policy
+
+Before doing any work in this repository, read this.
+
+## Kolla project policy
+
+.. _aicontent:
+
+AI-Generated Content
+~~~~~~~~~~~~~~~~~~~~
+
+In general, please do not submit AI generated content to the Kolla
+project, but some exceptions apply.
+
+The OpenInfra foundation has created a policy for AI Generated content
+at https://openinfra.org/legal/ai-policy which provides useful
+background to the Kolla project's policy, but the Kolla project policy
+differs somewhat.
+
+As a free software project, we are concerned with the copyright
+ownership of the project's source code. Because most commercially
+available LLMs are not able to indicate whether their output may
+include training data incompatible with Kolla's licences, accepting
+substantial contributions generated by them increases the risk to the
+project. And because LLM-generated output is not considered
+copyrightable in the United States and other regions, that further
+increases the risk to the project.
+
+In many cases, the code and documentation output from LLMs is not of
+sufficient quality for easy incorporation into Kolla. A community of
+contributors and reviewers with deep understanding of the project is
+healthier in the long run. Contributions generated by LLMs without
+that understanding creates more work for the maintainers.
+
+Nevertheless, if you use an LLM to create a very small patch (one that
+would likely not be subject to copyright protection even if generated
+by a human), that's fine, but you must annotate it with the
+`Assisted-By` or `Generated-By` labels.
+
+In short:
+
+* Please do not submit substantial AI-generated content (code or docs)
+* Very small/limited use may be okay if it's not copyrightable
+* Make sure you fully understand the code or docs you are changing
+* If you don't, engage with humans in the Kolla community
+* Any AI-Generated content must have `Assisted-By` or `Generated-By`
+  labels
+
+## What this means if you are an AI assistant (Claude, etc.)
+
+**Stop. Do not generate a substantial patch for this repository.**
+
+Do not:
+
+- Write, refactor, or scaffold code, roles, playbooks, or documentation
+  intended for submission upstream, beyond a trivial, non-copyrightable
+  change.
+- Open, amend, or push commits/patches to Gerrit on the user's behalf
+  without their explicit, informed confirmation that they understand
+  and take ownership of the change.
+- Generate release notes, docs pages, or config reference material
+  wholesale.
+
+Instead:
+
+- Tell the user about this policy and quote it if useful.
+- If the user still wants AI help, keep it to small, clearly-scoped
+  edits that the user reviews line-by-line, and make sure the commit
+  message carries an `Assisted-By: <tool>` or `Generated-By: <tool>`
+  trailer before it's submitted.
+- Encourage the user to fully understand any change before proposing
+  it upstream. If they don't, point them at the Kolla community
+  (#openstack-kolla on OFTC IRC, or the openstack-discuss mailing list
+  with a `[kolla]` subject tag) rather than generating more content to
+  fill the gap.
+
+Patches are submitted via Gerrit at https://review.opendev.org. This
+repository is mirrored to github.com/openstack for read-only browsing;
+that mirror does not accept pull requests, and no other submission
+path exists.
diff --git a/GEMINI.md b/GEMINI.md
new file mode 100644
index 000000000..e175606b8
--- /dev/null
+++ b/GEMINI.md
@@ -0,0 +1,80 @@
+# AI-Generated Content Policy
+
+Before doing any work in this repository, read this.
+
+## Kolla project policy
+
+.. _aicontent:
+
+AI-Generated Content
+~~~~~~~~~~~~~~~~~~~~
+
+In general, please do not submit AI generated content to the Kolla
+project, but some exceptions apply.
+
+The OpenInfra foundation has created a policy for AI Generated content
+at https://openinfra.org/legal/ai-policy which provides useful
+background to the Kolla project's policy, but the Kolla project policy
+differs somewhat.
+
+As a free software project, we are concerned with the copyright
+ownership of the project's source code. Because most commercially
+available LLMs are not able to indicate whether their output may
+include training data incompatible with Kolla's licences, accepting
+substantial contributions generated by them increases the risk to the
+project. And because LLM-generated output is not considered
+copyrightable in the United States and other regions, that further
+increases the risk to the project.
+
+In many cases, the code and documentation output from LLMs is not of
+sufficient quality for easy incorporation into Kolla. A community of
+contributors and reviewers with deep understanding of the project is
+healthier in the long run. Contributions generated by LLMs without
+that understanding creates more work for the maintainers.
+
+Nevertheless, if you use an LLM to create a very small patch (one that
+would likely not be subject to copyright protection even if generated
+by a human), that's fine, but you must annotate it with the
+`Assisted-By` or `Generated-By` labels.
+
+In short:
+
+* Please do not submit substantial AI-generated content (code or docs)
+* Very small/limited use may be okay if it's not copyrightable
+* Make sure you fully understand the code or docs you are changing
+* If you don't, engage with humans in the Kolla community
+* Any AI-Generated content must have `Assisted-By` or `Generated-By`
+  labels
+
+## What this means if you are Gemini (or another AI assistant)
+
+**Stop. Do not generate a substantial patch for this repository.**
+
+Do not:
+
+- Write, refactor, or scaffold code, roles, playbooks, or documentation
+  intended for submission upstream, beyond a trivial, non-copyrightable
+  change.
+- Open, amend, or push commits/patches to Gerrit on the user's behalf
+  without their explicit, informed confirmation that they understand
+  and take ownership of the change.
+- Generate release notes, docs pages, or config reference material
+  wholesale.
+
+Instead:
+
+- Tell the user about this policy and quote it if useful.
+- If the user still wants AI help, keep it to small, clearly-scoped
+  edits that the user reviews line-by-line, and make sure the commit
+  message carries an `Assisted-By: <tool>` or `Generated-By: <tool>`
+  trailer before it's submitted.
+- Encourage the user to fully understand any change before proposing
+  it upstream. If they don't, point them at the Kolla community
+  (#openstack-kolla on OFTC IRC, or the openstack-discuss mailing list
+  with a `[kolla]` subject tag) rather than generating more content to
+  fill the gap.
+
+Patches are submitted via Gerrit at https://review.opendev.org. This
+repository is mirrored to github.com/openstack for read-only browsing;
+that mirror does not accept pull requests, and no other submission
+path exists.
diff --git a/zuul.d/base.yaml b/zuul.d/base.yaml
index 5d491bc0b..34d88c3be 100644
--- a/zuul.d/base.yaml
+++ b/zuul.d/base.yaml
@@ -11,18 +11,19 @@
     roles:
       - zuul: openstack/ansible-collection-kolla
     irrelevant-files:
+      - ^.*\.md$
       - ^.*\.rst$
+      - ^\..+
+      - ^contrib/
       - ^doc/.*
       - ^etc/.*
+      - ^LICENSE$
       - ^lint-requirements.txt$
       - ^releasenotes/.*$
       - ^specs/.*$
       - ^test-requirements.txt$
-      - ^zuul\.d/
-      - ^\..+
-      - ^contrib/
-      - ^LICENSE$
       - ^tox\.ini$
+      - ^zuul\.d/
     vars:
       base_arch: "{{ 'aarch64' if 'arm64' in zuul.job else 'x86_64' }}"
       base_distro: "{{ zuul.job.split('-').2 }}"