From 82ebea7bae892fa08f048a91ab6df9eca79ff903 Mon Sep 17 00:00:00 2001 From: Sam Barker Date: Mon, 9 Mar 2026 12:21:31 +1300 Subject: [PATCH 1/9] Add AI contribution policy to CONTRIBUTING.md Sets out the project's position on AI-assisted contributions: contributors may use AI tools, but they own what they submit, must understand it, and must disclose significant AI usage. Also introduces the concept of AGENTS.md files in repositories. Closes #26 Assisted-by: Claude Opus 4.6 Signed-off-by: Sam Barker --- CONTRIBUTING.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a007ad7..bdc3245 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -35,6 +35,33 @@ The GitHub teams `@kroxylicious/code-reviewers` and `@kroxylicious/doc-reviewers 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 may use AI tools (such as LLMs, code assistants, and similar) when preparing contributions to Kroxylicious. +Like any tool, what matters is the quality of the result and that the contributor understands what they are submitting. + +When you submit a contribution you are the contributor, regardless of what tools you used to produce it. +You are responsible for understanding what you are contributing and ensuring it meets the project's standards. + +### Requirements + +* **You are the contributor.** When you sign off the [DCO](./DCO.txt), you are certifying the contribution as your own. + AI-generated or AI-assisted content does not change this obligation. +* **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 understand. +* **Disclose AI usage.** If AI tools played a significant role in producing a contribution, note this in the pull request description. + A brief mention is sufficient (e.g. "AI-assisted" or naming the tool used). +* **Ensure originality and licensing compliance.** You are responsible for verifying that AI-generated content does not + introduce intellectual property or licensing concerns incompatible with the project's [license](./LICENSE). +* **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. + +### AGENTS.md + +Individual repositories within the Kroxylicious organisation may 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 are using an AI tool to help prepare a contribution, ensure it has access to the relevant `AGENTS.md` so that its output aligns with project norms. + ## I just have a question If you encounter any issues while using Kroxylicious, you can get help using: From 87063db33e56dc7a8cd80a75943d7640c0ee4ba8 Mon Sep 17 00:00:00 2001 From: Sam Barker Date: Mon, 9 Mar 2026 12:31:53 +1300 Subject: [PATCH 2/9] Specify Assisted-by commit trailer for AI disclosure Adds guidance on using an Assisted-by trailer in commit messages to identify the AI tool and model used. The trailer is intended to be populated by the tooling itself, with AGENTS.md providing tool-specific configuration details. Assisted-by: Claude Opus 4.6 Signed-off-by: Sam Barker --- CONTRIBUTING.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bdc3245..91990a4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -50,7 +50,8 @@ You are responsible for understanding what you are contributing and ensuring it * **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 understand. * **Disclose AI usage.** If AI tools played a significant role in producing a contribution, note this in the pull request description. - A brief mention is sufficient (e.g. "AI-assisted" or naming the tool used). + Commits should include an `Assisted-by` trailer identifying the tool and model used (e.g. `Assisted-by: Claude Opus 4.6 `). + Most AI coding tools can be configured to add this automatically — see the repository's `AGENTS.md` for details. * **Ensure originality and licensing compliance.** You are responsible for verifying that AI-generated content does not introduce intellectual property or licensing concerns incompatible with the project's [license](./LICENSE). * **Meet the same quality bar.** AI-assisted contributions are reviewed to the same standard as any other contribution. From 5ce3afb305a5c92f47c56e4b8db73a49a29183e3 Mon Sep 17 00:00:00 2001 From: Sam Barker Date: Mon, 9 Mar 2026 12:41:51 +1300 Subject: [PATCH 3/9] Add project tech stack overview to CONTRIBUTING.md Adds a brief 'About the Project' section noting Kroxylicious is a Java project built with Apache Maven. Assisted-by: Claude Opus 4.6 Signed-off-by: Sam Barker --- CONTRIBUTING.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 91990a4..154e924 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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 may have additional details in their `README.md` or `AGENTS.md` files. + ## How can I contribute You can contribute by: From 086469a537e97c7d9435106dacaf56eea98f6aae Mon Sep 17 00:00:00 2001 From: Sam Barker Date: Mon, 9 Mar 2026 13:41:18 +1300 Subject: [PATCH 4/9] Add org-level AGENTS.md for AI tooling guidance Provides AI coding tools with process expectations including DCO sign-off, Assisted-by trailers, commit discipline, and pull request review requirements. Clarifies that human committer review and merge decisions are not substituted by AI reviews. Assisted-by: Claude Opus 4.6 Signed-off-by: Sam Barker --- AGENTS.md | 47 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..379b834 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,47 @@ +# Kroxylicious AI Agent Guidelines + +This file provides guidance to AI coding tools (such as GitHub Copilot, Claude Code, and similar) when working on repositories within the Kroxylicious organisation. + +Contributors using AI tools should ensure their tool has access to this file and any repository-specific `AGENTS.md`. +Please also read the [Contributing Guidelines](./CONTRIBUTING.md), in particular the section on [Use of AI Assistance](./CONTRIBUTING.md#use-of-ai-assistance). + +## Contribution Process + +### DCO Sign-off + +All commits must be signed off with the Developer Certificate of Origin (DCO). +Use `git commit -s` to add the sign-off automatically. + +### Assisted-by Trailer + +Commits produced with AI assistance must include an `Assisted-by` trailer identifying the tool and model. +The trailer should be added to the commit message body, after the sign-off: + +``` + + +Signed-off-by: Name +Assisted-by: +``` + +### Commit Discipline + +- Each commit should be atomic and represent a single logical change. +- Write clear, descriptive commit messages that explain *why* the change was made, not just *what* changed. +- Keep commits small enough to be reviewed in a few minutes. + +### Pull Requests + +- All changes must be submitted as pull requests. +- At least one human [Committer](./COMMITTERS.md) must review and approve a pull request before it is merged. + Automated or AI-assisted reviews (such as security or style checks) may supplement but do not substitute for human review. + The decision to merge is always made by a human committer. +- PR descriptions should summarise the change and note any AI tool involvement. +- Ensure all CI checks pass before requesting review. + +## Technical Foundations + +Kroxylicious is built with Java and [Apache Maven](https://maven.apache.org/). +Individual repositories will have their own `AGENTS.md` with specific build commands, architecture details, coding conventions, and testing expectations. + +When working on a specific repository, always prefer guidance from that repository's `AGENTS.md` over this file for technical matters. From 03f4f85a82c784c2f376c58807403f4db56f6be4 Mon Sep 17 00:00:00 2001 From: Sam Barker Date: Mon, 9 Mar 2026 13:50:09 +1300 Subject: [PATCH 5/9] Clarify AI review and merge policy Adds language to both CONTRIBUTING.md and AGENTS.md clarifying that AI-assisted reviews supplement but do not substitute for Committer review, and that merge decisions follow the project's decision making framework. Assisted-by: Claude Opus 4.6 Signed-off-by: Sam Barker --- AGENTS.md | 2 +- CONTRIBUTING.md | 2 ++ 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 379b834..33c4710 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -35,7 +35,7 @@ Assisted-by: - All changes must be submitted as pull requests. - At least one human [Committer](./COMMITTERS.md) must review and approve a pull request before it is merged. Automated or AI-assisted reviews (such as security or style checks) may supplement but do not substitute for human review. - The decision to merge is always made by a human committer. + The decision to merge is always made by human Committer(s) following the project's [decision making](./GOVERNANCE.md#decision-making) framework. - PR descriptions should summarise the change and note any AI tool involvement. - Ensure all CI checks pass before requesting review. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 154e924..c950985 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -36,6 +36,8 @@ 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) may supplement but do not substitute for review by a Committer. +The decision to merge is always made by Committer(s) following the project's [decision making](./GOVERNANCE.md#decision-making) framework. 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. From 1ed42416b849b1f5d9fc16bff4a47a5a52fa6a3a Mon Sep 17 00:00:00 2001 From: Sam Barker Date: Mon, 9 Mar 2026 14:03:27 +1300 Subject: [PATCH 6/9] Improve agent guidance for reviewability Adds guidance on commit messages (why not what), cohesive PRs, PR descriptions focused on problems and trade-offs, and naming conventions that prefer intent over encoded logic. Assisted-by: Claude Opus 4.6 Signed-off-by: Sam Barker --- AGENTS.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 33c4710..8b15769 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -27,18 +27,26 @@ Assisted-by: ### Commit Discipline - Each commit should be atomic and represent a single logical change. -- Write clear, descriptive commit messages that explain *why* the change was made, not just *what* changed. - Keep commits small enough to be reviewed in a few minutes. +- Commit messages should explain *why* the change was made, not *what* changed. Reviewers read diffs — they can see what changed. Focus on the problem being solved, the reasoning, or the decision made. ### Pull Requests +- A pull request should address a single cohesive goal. Do not bundle unrelated changes together — each PR should tell a clear story that a reviewer can follow from start to finish. - All changes must be submitted as pull requests. - At least one human [Committer](./COMMITTERS.md) must review and approve a pull request before it is merged. Automated or AI-assisted reviews (such as security or style checks) may supplement but do not substitute for human review. The decision to merge is always made by human Committer(s) following the project's [decision making](./GOVERNANCE.md#decision-making) framework. -- PR descriptions should summarise the change and note any AI tool involvement. +- PR descriptions should focus on the problem being addressed, the approach taken, and any trade-offs or alternatives considered. Note any AI tool involvement. - Ensure all CI checks pass before requesting review. +### Naming and Comments + +Prefer code that is self-describing through clear naming and structure. +A well-chosen name is almost always better than a comment. +Names should convey intent and purpose, not encode implementation logic — logic in a name will drift from reality just as quickly as a stale comment. +Reserve comments for reasoning or constraints that good naming alone cannot convey, but if you find yourself reaching for a comment, first consider whether a rename would make it unnecessary. + ## Technical Foundations Kroxylicious is built with Java and [Apache Maven](https://maven.apache.org/). From 35a2309d5050f16ce74e8ae31154db617d0d6a9b Mon Sep 17 00:00:00 2001 From: Sam Barker Date: Tue, 10 Mar 2026 09:24:44 +1300 Subject: [PATCH 7/9] Strengthen copyright and contributor understanding language Explicitly requires AI-generated content must not reproduce copyrighted material and that contributors enable available controls to reduce that risk. Adds that PRs may be closed where the contributor does not appear to understand their submission. Adds matching copyright instruction to AGENTS.md. Assisted-by: Claude Opus 4.6 Signed-off-by: Sam Barker --- AGENTS.md | 6 ++++++ CONTRIBUTING.md | 7 +++++-- 2 files changed, 11 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 8b15769..8ef4d79 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -40,6 +40,12 @@ Assisted-by: - PR descriptions should focus on the problem being addressed, the approach taken, and any trade-offs or alternatives considered. Note any AI tool involvement. - Ensure all CI checks pass before requesting review. +### Copyright and Licensing + +Do not reproduce copyrighted material in generated code, documentation, or other content. +If you are aware of controls or configuration that reduce the risk of reproducing copyrighted content, ensure they are active. +All contributions must be compatible with the project's [license](./LICENSE). + ### Naming and Comments Prefer code that is self-describing through clear naming and structure. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c950985..5b4b318 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -59,10 +59,13 @@ You are responsible for understanding what you are contributing and ensuring it * **Disclose AI usage.** If AI tools played a significant role in producing a contribution, note this in the pull request description. Commits should include an `Assisted-by` trailer identifying the tool and model used (e.g. `Assisted-by: Claude Opus 4.6 `). Most AI coding tools can be configured to add this automatically — see the repository's `AGENTS.md` for details. -* **Ensure originality and licensing compliance.** You are responsible for verifying that AI-generated content does not - introduce intellectual property or licensing concerns incompatible with the project's [license](./LICENSE). +* **Ensure originality and licensing compliance.** AI-generated content must not reproduce copyrighted material. + You are responsible for verifying that your contribution does not introduce intellectual property or licensing concerns + incompatible with the project's [license](./LICENSE). Where your AI tool offers controls to reduce the risk of + reproducing copyrighted content, ensure 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. ### AGENTS.md From 9f2e062e37f4811987832294314ef02c8023781c Mon Sep 17 00:00:00 2001 From: Sam Barker Date: Tue, 10 Mar 2026 09:35:48 +1300 Subject: [PATCH 8/9] Add conciseness and PR focus guidance Adds conciseness requirement to both CONTRIBUTING.md and AGENTS.md. Adds PR review guidance that unfocused or oversized PRs may be closed and the contributor asked to break them down. These apply to all contributions regardless of how they were produced. Assisted-by: Claude Opus 4.6 Signed-off-by: Sam Barker --- AGENTS.md | 6 ++++++ CONTRIBUTING.md | 5 +++++ 2 files changed, 11 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 8ef4d79..5de97d1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -40,6 +40,12 @@ Assisted-by: - PR descriptions should focus on the problem being addressed, the approach taken, and any trade-offs or alternatives considered. Note any AI tool involvement. - Ensure all CI checks pass before requesting review. +### Conciseness + +Be concise and efficient in all generated content. +Do not produce filler, boilerplate explanations, or unnecessary verbosity. +Stay focused on the goal at hand — reviewers' time is limited and every line should earn its place. + ### Copyright and Licensing Do not reproduce copyrighted material in generated code, documentation, or other content. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5b4b318..e3c6e19 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -38,6 +38,9 @@ All changes which are to be committed in project source control must be reviewed 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) may supplement but do not substitute for review by a Committer. The decision to merge is always made by Committer(s) following the project's [decision making](./GOVERNANCE.md#decision-making) framework. +Pull requests should be focused on a single goal and 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. @@ -66,6 +69,8 @@ You are responsible for understanding what you are contributing and ensuring it * **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 text faster than reviewers can read it. + Contributions, PR descriptions, and issue comments should be clear, focused, and free of unnecessary verbosity. ### AGENTS.md From 0ad85ef76b996b4eafd8966e017bf61a62bd1f4c Mon Sep 17 00:00:00 2001 From: Sam Barker Date: Tue, 10 Mar 2026 10:27:51 +1300 Subject: [PATCH 9/9] Clarify when AI disclosure is and isn't required Routine IDE-like AI features (code completion, spelling) do not require disclosure. Disclosure is expected when AI generates substantial content such as functions, tests, or documentation. Assisted-by: Claude Opus 4.6 Signed-off-by: Sam Barker --- CONTRIBUTING.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e3c6e19..1d91ca2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -62,6 +62,8 @@ You are responsible for understanding what you are contributing and ensuring it * **Disclose AI usage.** If AI tools played a significant role in producing a contribution, note this in the pull request description. Commits should include an `Assisted-by` trailer identifying the tool and model used (e.g. `Assisted-by: Claude Opus 4.6 `). Most AI coding tools can be configured to add this automatically — see the repository's `AGENTS.md` for details. + Use of AI features in the same way you would use an IDE — code completion, spelling, and the like — does not require disclosure. + Disclosure is expected when AI tools are used to generate substantial content such as functions, tests, documentation, or design approaches. * **Ensure originality and licensing compliance.** AI-generated content must not reproduce copyrighted material. You are responsible for verifying that your contribution does not introduce intellectual property or licensing concerns incompatible with the project's [license](./LICENSE). Where your AI tool offers controls to reduce the risk of