diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..fa02358 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,68 @@ +# Kroxylicious AI Agent Guidelines + +This file provides guidance for AI coding tools, such as GitHub Copilot and Claude Code, when working in Kroxylicious repositories. + +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 + +### 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 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: + +``` + + +Signed-off-by: Name +Assisted-by: +``` + +### Commit Discipline + +- 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 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. +- 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, 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 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 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 + +Write code that is self-describing through clear naming and structure. +A well-chosen name is almost always better than a comment. +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/). +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 a007ad7..bc1da4c 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 include a `README.md` with context, build, and usage instructions. + ## How can I contribute You can contribute by: @@ -31,10 +36,47 @@ 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. +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. + +### 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. +* **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. +* **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. + 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 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 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 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. + ## I just have a question If you encounter any issues while using Kroxylicious, you can get help using: