From ebf465648190810e6d6ae47af011dd87228ffdc4 Mon Sep 17 00:00:00 2001 From: Blaine Gardner Date: Thu, 16 Apr 2026 15:11:37 -0600 Subject: [PATCH] doc: add AI guidelines Add AI guidelines based on discussions from the most recent community meeting. Signed-off-by: Blaine Gardner --- .github/PULL_REQUEST_TEMPLATE.md | 1 + CONTRIBUTING.md | 4 +++ Documentation/Contributing/.pages | 1 + Documentation/Contributing/ai-guidelines.md | 27 +++++++++++++++++++ .../Contributing/development-flow.md | 6 +++++ 5 files changed, 39 insertions(+) create mode 100644 Documentation/Contributing/ai-guidelines.md diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 52b3b7ade..b7f86cc04 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -16,6 +16,7 @@ Resolves # - [ ] **Commit Message Formatting**: Commit titles and messages follow guidelines in the [developer guide](https://rook.io/docs/rook/latest/Contributing/development-flow/#commit-structure). - [ ] Reviewed the developer guide on [Submitting a Pull Request](https://rook.io/docs/rook/latest/Contributing/development-flow/#submitting-a-pull-request) +- [ ] Reviewed [AI guidelines](https://rook.io/docs/rook/latest/Contributing/ai-guidelines), if AI assisted with the PR. - [ ] [Pending release notes](https://github.com/rook/rook/blob/master/PendingReleaseNotes.md) updated with breaking and/or notable changes for the next minor release. - Overwriting Ceph's configurations should be marked as breaking changes. - [ ] Documentation has been updated, if necessary. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b39f1fde1..3b8a40216 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -106,6 +106,10 @@ second line is always blank, and other lines should be wrapped at 80 characters. This allows the message to be easier to read on GitHub as well as in various git tools. +## AI Guidelines + +Review Rook's [AI Guidelines](https://rook.io/docs/rook/latest/Contributing/ai-guidelines) + ## Change Approval The Rook project aims to empower contributors to approve and merge code changes autonomously. diff --git a/Documentation/Contributing/.pages b/Documentation/Contributing/.pages index f1474069f..6b39b3abc 100644 --- a/Documentation/Contributing/.pages +++ b/Documentation/Contributing/.pages @@ -1,5 +1,6 @@ nav: - development-flow.md + - ai-guidelines.md - development-environment.md - documentation.md - ... diff --git a/Documentation/Contributing/ai-guidelines.md b/Documentation/Contributing/ai-guidelines.md new file mode 100644 index 000000000..af7ea64bf --- /dev/null +++ b/Documentation/Contributing/ai-guidelines.md @@ -0,0 +1,27 @@ +--- +title: AI Guidelines +--- + +Rook's AI guidelines are focused on preserving trust. Thousands of Rook users trust Rook and its maintainers to release enterprise-grade software with as few issues as possible and with as much transparency as possible. Each person who contributes code to Rook must be able to do so in a way that preserves maintainer trust, and by extension, user trust. + +## Legal requirements + +As a CNCF project, Rook follows the [Linux Foundation Guidelines](https://www.linuxfoundation.org/legal/generative-ai) for ensuring legal compliance. These guidelines require contributors to check (in summary): + +1. AI tool restrictions: Contributors must ensure the AI tool's terms don't impose contractual limitations that conflict with the project's license. +2. Third-party content permissions: If generated output contains copyrighted materials from others, contributors must confirm proper permissions exist (via compatible license) and provide license information when contributing. + +In order to ensure legal guidelines, Rook requires human involvement and engagement and does not allow fully-autonomous or near-fully-autonomous "bots" to submit issues or pull requests. If Rook maintainers have reasonable cause to believe a contribution does not have human oversight, it will be rejected. + +## Transparency requirements + +1. Contributors should disclose in pull request descriptions how AI tools assisted in development. E.g., generating substantial functions, documentation, and/or unit tests. +2. Rook requires human sign-off. Signing commits using an AI tool, or listing AI tooling in commits using `co-authored-by`, `assisted-by`, `generated-by`, or using similar commit trailers is not necessary. + +## Best practices to respect maintainer time + +AI models are making it much easier to contribute code to open source, and maintainer time is limited. + +1. Consider opening an issue following [issue guidelines](development-flow.md#begin-with-an-issue) before contributing. +2. Do not submit large AI-generated PRs without previous design discussion. Follow [Kubernetes's guidelines for large/automatic edits](https://www.kubernetes.dev/docs/guide/pull-requests/#large-or-automatic-edits) as needed. +3. Do not use LLM output to write commit messages or GitHub comments. Reviewers are interested in knowing your reasoning about the code you submitted for review. It's yours to own and explain. Automated responses may result in a PR being rejected. diff --git a/Documentation/Contributing/development-flow.md b/Documentation/Contributing/development-flow.md index 592c1cb61..03a61d5a8 100644 --- a/Documentation/Contributing/development-flow.md +++ b/Documentation/Contributing/development-flow.md @@ -136,6 +136,12 @@ rook To submit a change, create a branch in your fork and then submit a pull request (PR) from the branch. +### Begin with an Issue + +Before working on code changes requiring more than a simple bug fix, maintainers recommend creating a GitHub issue, including filling in the issue template. +Discuss options for appropriate issue resolution with maintainers, and get confirmation before creating a pull request. +This can help avoid unnecessary work needed when the design approach needs substantially changed before a contribution can be merged. + ### Design Document For new features of significant scope and complexity, a design document is recommended before work begins on the implementation.