From 82ebea7bae892fa08f048a91ab6df9eca79ff903 Mon Sep 17 00:00:00 2001 From: Sam Barker Date: Mon, 9 Mar 2026 12:21:31 +1300 Subject: [PATCH 01/11] 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 02/11] 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 03/11] 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 04/11] 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 05/11] 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 06/11] 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 07/11] 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 08/11] 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 09/11] 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 From 0220edc07c2054dcacaa0787bff1abcf215b2840 Mon Sep 17 00:00:00 2001 From: Sam Barker Date: Fri, 20 Mar 2026 22:38:25 +1300 Subject: [PATCH 10/11] Apply readability improvements from PR review feedback Address all suggestion-style comments from @PaulRMellor: tighten wording, prefer active/imperative voice, and remove vague phrasing. Also make the Maven build line in AGENTS.md actionable, and clarify the CONTRIBUTING.md project intro to focus on human readers. Assisted-by: Claude Sonnet 4.6 Signed-off-by: Sam Barker --- AGENTS.md | 33 +++++++++++++++++---------------- CONTRIBUTING.md | 17 ++++++++--------- 2 files changed, 25 insertions(+), 25 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 5de97d1..fa02358 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,8 +1,8 @@ # 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. +This file provides guidance for AI coding tools, such as GitHub Copilot and Claude Code, when working in Kroxylicious repositories. -Contributors using AI tools should ensure their tool has access to this file and any repository-specific `AGENTS.md`. +Contributors using AI tools must ensure the tools can access this file and any repository-specific `AGENTS.md` file. 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 @@ -14,8 +14,8 @@ 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: +Commits created with AI assistance must include an `Assisted-by` trailer identifying the tool and model. +Add the trailer to the commit message body after the sign-off: ``` @@ -26,42 +26,43 @@ Assisted-by: ### Commit Discipline -- Each commit should be atomic and represent a single logical change. +- Each commit must be atomic and represent a single logical change. - 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. +- Commit messages should explain *why* the change was made, not *what* changed. Reviewers can see the code changes in the diff. 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. +- Submit all changes 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 focus on the problem being addressed, the approach taken, and any trade-offs or alternatives considered. Note any AI tool involvement. + Automated or AI-assisted reviews, such as security or style checks, can supplement human review but do not replace it. + The decision to merge is always made by human committers following the project's [decision making](./GOVERNANCE.md#decision-making) framework. +- PR descriptions must focus on the problem being addressed, the approach taken, and any trade-offs or alternatives considered. They must also 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. +Stay focused on the goal at hand — reviewers' time is limited and every line should add value. ### 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. +If you are aware of controls or configuration that reduce or remove 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. +Write 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. +Names must convey intent and purpose, not implementation logic, which can become outdated as quickly as a stale comment. +Use 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/). -Individual repositories will have their own `AGENTS.md` with specific build commands, architecture details, coding conventions, and testing expectations. +Use `mvn verify` to build and test unless the repository's `AGENTS.md` specifies otherwise. +Individual repositories typically include an `AGENTS.md` file with 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. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1d91ca2..e3dcef9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -9,7 +9,7 @@ Any unacceptable behavior should be reported to [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. +Individual repositories include a `README.md` with context, build, and usage instructions. ## How can I contribute @@ -36,9 +36,9 @@ 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. -Pull requests should be focused on a single goal and sized for effective review. +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. @@ -47,15 +47,14 @@ If you're willing to provide code and/or reviews to others then let one of the [ ## 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. +Contributors can use AI tools, such as LLMs and code assistants, when preparing contributions to Kroxylicious. +As with any tool, the contributor is responsible for the quality of the result and for understanding what they submit. -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. +You are responsible for understanding your 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 are certifying the contribution as your own. +* **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. * **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. From ea9f8b793f8ac89bf390aa963101c07abacde766 Mon Sep 17 00:00:00 2001 From: Sam Barker Date: Fri, 20 Mar 2026 23:11:49 +1300 Subject: [PATCH 11/11] Apply readability suggestions from PR review feedback Apply wording improvements suggested by @PaulRMellor: - Clarify "fully understand" in contribution requirement - Use present tense "play" instead of "played" for AI disclosure - Strengthen "should" to "must" for Assisted-by trailer - Simplify IDE comparison sentence - Strengthen "expected" to "required" for disclosure threshold - Rework licensing compliance sentence for clarity - "text" -> "content" and "verbosity" -> "detail" in conciseness bullet - "may" -> "can" for AGENTS.md repositories - Rephrase AGENTS.md access sentence, "norms" -> "conventions" Assisted-by: Claude Sonnet 4.6 Signed-off-by: Sam Barker --- CONTRIBUTING.md | 22 ++++++++++------------ 1 file changed, 10 insertions(+), 12 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e3dcef9..bc1da4c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -57,27 +57,25 @@ You are responsible for understanding your contribution and ensuring that it mee * **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. * **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. - Commits should include an `Assisted-by` trailer identifying the tool and model used (e.g. `Assisted-by: Claude Opus 4.6 `). + Do not submit code, documentation, or other content that you do not fully understand. +* **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 `). 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. + 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. * **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. + You must verify that your contribution does not introduce intellectual property or licensing issues that are incompatible with the project's [License](./LICENSE). If your AI tool provides controls to reduce the risk of reproducing copyrighted content, make sure that 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 text faster than reviewers can read it. - Contributions, PR descriptions, and issue comments should be clear, focused, and free of unnecessary verbosity. +* **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. ### AGENTS.md -Individual repositories within the Kroxylicious organisation may include an `AGENTS.md` file. +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 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. +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. ## I just have a question