Skip to content

docs: document AI contribution policy and agent guidelines #27

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
SamBarker wants to merge 13 commits into
base: main
Choose a base branch
from
+43 −0
Open

docs: document AI contribution policy and agent guidelines #27

Changes from all commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
82ebea7
Add AI contribution policy to CONTRIBUTING.md
SamBarker Mar 8, 2026
87063db
Specify Assisted-by commit trailer for AI disclosure
SamBarker Mar 8, 2026
5ce3afb
Add project tech stack overview to CONTRIBUTING.md
SamBarker Mar 8, 2026
086469a
Add org-level AGENTS.md for AI tooling guidance
SamBarker Mar 9, 2026
03f4f85
Clarify AI review and merge policy
SamBarker Mar 9, 2026
1ed4241
Improve agent guidance for reviewability
SamBarker Mar 9, 2026
35a2309
Strengthen copyright and contributor understanding language
SamBarker Mar 9, 2026
9f2e062
Add conciseness and PR focus guidance
SamBarker Mar 9, 2026
0ad85ef
Clarify when AI disclosure is and isn't required
SamBarker Mar 9, 2026
0220edc
Apply readability improvements from PR review feedback
SamBarker Mar 20, 2026
ea9f8b7
Apply readability suggestions from PR review feedback
SamBarker Mar 20, 2026
3bcde2b
Remove AGENTS.md from this PR
SamBarker Apr 1, 2026
7e7d941
Rework copyright language and require own-words review responses
SamBarker 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
43 changes: 43 additions & 0 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,11 @@ This project and everyone participating in it is governed by the [Code of Conduc
By participating, you are expected to uphold this code.
Any unacceptable behavior should be reported to [kroxylicious-admins@redhat.com](mailto:kroxylicious-admins@redhat.com).

## About the Project

Kroxylicious is a Java project built with [Apache Maven](https://maven.apache.org/).
Individual repositories include a `README.md` with context, build, and usage instructions.

## How can I contribute

You can contribute by:
Expand All @@ -31,10 +36,48 @@ in your pull request. Alternatively, to signoff a bunch of commits you can use `

All changes which are to be committed in project source control must be reviewed by at least one [Committer](COMMITTERS.md) before being merged.
If the change is being authored by someone who is a Committer, that change must be reviewed by at least one other Committer before being merged.
Automated or AI-assisted reviews, such as security or style checks, can supplement review but do not replace review by a Committer.
Committers make merge decisions following the project's [decision-making](./GOVERNANCE.md#decision-making) framework.
Pull requests must focus on a single goal and be sized for effective review.
We may close pull requests that are unfocused or too large to review effectively, and ask the contributor to break them into smaller, more reviewable changes.

The GitHub teams `@kroxylicious/code-reviewers` and `@kroxylicious/doc-reviewers` can be used to request a PR review from contributors.

If you're willing to provide code and/or reviews to others then let one of the [project managers](PMs.md) know and we can add you to the relevant GitHub team.

## Use of AI Assistance

Contributors can use AI tools, such as LLMs and code assistants, when preparing contributions to Kroxylicious.
Copy link
Copy Markdown
Member

@tombentley tombentley Mar 26, 2026

Choose a reason for hiding this comment

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

Suggested change
Contributors can use AI tools, such as LLMs and code assistants, when preparing contributions to Kroxylicious.
Contributors can use AI tools, such as LLMs and code assistants, when preparing contributions to Kroxylicious.
PRs must always be submitted by a human, and the requirement for commits to have DCO signoff can only be met by a human.
When signing off for DCO purposes you are taking responsibility for the LLM's output.

As with any tool, the contributor is responsible for the quality of the result and for understanding what they submit.

You are responsible for understanding your contribution and ensuring that it meets project standards, regardless of the tools used.
Copy link
Copy Markdown
Member

@tombentley tombentley Mar 22, 2026

Choose a reason for hiding this comment

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

"You" is assumed to be a human. We're basically assuming that there's a human in the loop for opening the PR. That might be what we want, or not. But either way we should be explicit about what our expectations are.

Copy link
Copy Markdown
Member

@tombentley tombentley Mar 26, 2026

Choose a reason for hiding this comment

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

Suggested change
You are responsible for understanding your contribution and ensuring that it meets project standards, regardless of the tools used.
The PR submitter is responsible for understanding their contribution and ensuring that it meets project standards, regardless of the tools used.


### Requirements

* **You are the contributor.** When you sign off the [DCO](./DCO.txt), you certify the contribution as your own.
AI-generated or AI-assisted content does not change this obligation.
Comment on lines +57 to +58
Copy link
Copy Markdown
Member

@tombentley tombentley Mar 22, 2026

Choose a reason for hiding this comment

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

I think we can be a bit clearer on this point: The project requires DCO on all commits. The DCO requires that signoff is done by a legal person. An AI is not a legal entity so it cannot sign off. When a person signs off on the commit they're taking responsibility for an AI assistance included in that commit.

* **Understand your contribution.** You must have a clear understanding of what your contribution does and why.
Do not submit code, documentation, or other content that you do not fully understand.
Copy link
Copy Markdown
Member

@tombentley tombentley Mar 22, 2026

Choose a reason for hiding this comment

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

Suggested change
Do not submit code, documentation, or other content that you do not fully understand.
Do not submit code, documentation, or other content that you do not fully understand.
You should be able to answer reviewers' questions yourself, without recourse to AI.
In particular, do not waste the time of other contributors by being a proxy between reviewers and an AI.

You must be able to explain your changes and respond to reviewer feedback in your own words, without relying on AI tools to answer review questions.
* **Disclose AI usage.** If AI tools play a significant role in a contribution, note this in the pull request description.
Commits must include an `Assisted-by` trailer that identifies the tool and model used (for example, `Assisted-by: Claude Opus 4.6 <noreply@anthropic.com>`).
Most AI coding tools can be configured to add this automatically — see the repository's `AGENTS.md` for details.
Copy link
Copy Markdown
Member

@tombentley tombentley Apr 1, 2026

Choose a reason for hiding this comment

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

Suggested change
Most AI coding tools can be configured to add this automatically — see the repository's `AGENTS.md` for details.
Most AI coding tools can be configured to add this automatically.

Let's drop the AGENTS.md for now, until we know we'll actually have AGENTS.md in each repo.

Using AI features in the same way as an IDE, such as code completion or spelling, does not require disclosure.
Disclosure is required when AI tools are used to generate substantial content such as functions, tests, documentation, or design approaches.
Copy link
Copy Markdown
Member

@tombentley tombentley Mar 22, 2026

Choose a reason for hiding this comment

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

Why should the project really care about AI usage in a design?

* **Ensure licensing compliance.** AI-generated content must not introduce material under licenses incompatible with the project's [License](./LICENSE).
If your AI tool provides controls to reduce the risk of reproducing third-party code without appropriate attribution or license compatibility, make sure they are enabled.
* **Meet the same quality bar.** AI-assisted contributions are reviewed to the same standard as any other contribution.
Code must be correct, maintainable, tested, and consistent with project conventions.
We may close pull requests where the contributor does not appear to understand the contribution they have submitted.
* **Be concise.** AI tools can generate content faster than reviewers can read it.
Contributions, PR descriptions, and issue comments should be clear, focused, and free of unnecessary detail.
Copy link
Copy Markdown
Member

@tombentley tombentley Apr 1, 2026

Choose a reason for hiding this comment

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

Suggested change
Contributions, PR descriptions, and issue comments should be clear, focused, and free of unnecessary detail.
Contributions, PR descriptions, and issue comments should be clear, focused, and free of unnecessary detail. Please respect the time of the other contributors in the community.


### AGENTS.md

Individual repositories within the Kroxylicious organisation can include an `AGENTS.md` file.
These files provide AI tools with project-specific context such as build instructions, architecture, coding conventions, and testing expectations.
If you use an AI tool to help prepare a contribution, ensure that it can access the relevant `AGENTS.md` so that its output aligns with project conventions.
Comment on lines +75 to +79
Copy link
Copy Markdown
Member

@tombentley tombentley Apr 1, 2026

Choose a reason for hiding this comment

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

I think we should drop this section for now. I don't think we need it in order to make a start with adding AGENTS.md (or anything else). And it would seem to commit us to having those files. We can always circle back and add a section like this in a month or two once we know a bit more clearly what we're doing.


## I just have a question

If you encounter any issues while using Kroxylicious, you can get help using:
Expand Down