diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..5de97d1 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,67 @@ +# 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. +- 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 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. +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. +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/). +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. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a007ad7..1d91ca2 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: @@ -31,10 +36,50 @@ 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. +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 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. + 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 + 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. +* **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 + +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: