From fbd968611cbae1871457da1d39b8daf410cfb144 Mon Sep 17 00:00:00 2001 From: Charlie Le Date: Fri, 3 Apr 2026 11:24:53 -0700 Subject: [PATCH 1/7] Add Generative AI Contribution Policy Create GENAI_POLICY.md to set clear expectations for AI-assisted contributions across cortexproject repos, covering permitted uses, contributor responsibilities, disclosure requirements, and maintainer authority. Also add references from CONTRIBUTING.md, docs/contributing/_index.md, the PR template checklist, and a "Related Policies" section in AGENTS.md clarifying the distinction between guidance *to* AI agents and policy governing *human use* of AI tools. Fixes #7388 Co-Authored-By: Claude Opus 4.6 (1M context) Signed-off-by: Charlie Le --- .github/pull_request_template.md | 1 + AGENTS.md | 4 +++ CONTRIBUTING.md | 2 ++ GENAI_POLICY.md | 62 ++++++++++++++++++++++++++++++++ docs/contributing/_index.md | 7 ++++ 5 files changed, 76 insertions(+) create mode 100644 GENAI_POLICY.md diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index d5c4e33985d..fa5913a75a7 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -13,3 +13,4 @@ Fixes # - [ ] Tests updated - [ ] Documentation added - [ ] `CHANGELOG.md` updated - the order of entries should be `[CHANGE]`, `[FEATURE]`, `[ENHANCEMENT]`, `[BUGFIX]` +- [ ] If AI-assisted: significant AI usage disclosed (see [GenAI Policy](GENAI_POLICY.md)) diff --git a/AGENTS.md b/AGENTS.md index 139da527444..dcb08b36bd3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -114,3 +114,7 @@ Import order: stdlib, third-party packages, internal Cortex packages (separated - Sign commits with DCO: `git commit -s -m "message"` - Run `make doc` if config/flags changed - Include CHANGELOG entry for user-facing changes + +## Related Policies + +This file (`AGENTS.md`) provides technical guidance **to** AI coding agents working in this repository (build commands, architecture, conventions). For the policy governing **human use** of AI tools when preparing contributions, see [GENAI_POLICY.md](GENAI_POLICY.md). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1186e1ce336..476ffc52b1c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,3 +1,5 @@ # Contributing to Cortex See [https://cortexmetrics.io/docs/contributing/](https://cortexmetrics.io/docs/contributing/). + +If using generative AI tools, please also review our [Generative AI Contribution Policy](GENAI_POLICY.md). diff --git a/GENAI_POLICY.md b/GENAI_POLICY.md new file mode 100644 index 00000000000..af5e688b573 --- /dev/null +++ b/GENAI_POLICY.md @@ -0,0 +1,62 @@ +# Generative AI Contribution Policy + +## Purpose + +The Cortex project welcomes contributions that make use of generative AI (GenAI) tools. AI assistants can help contributors write code, explore the codebase, draft documentation, and improve productivity. However, **humans bear full responsibility** for every contribution they submit, regardless of how it was produced. + +This policy applies to all repositories under the [cortexproject](https://github.com/cortexproject) GitHub organisation. + +## Permitted Use of AI Tools + +The following uses of AI tools are encouraged and permitted: + +- **Coding assistants** - Using tools like GitHub Copilot, Claude Code, Cursor, or similar to help write, refactor, or debug code. +- **Codebase exploration** - Querying AI tools to understand project architecture, locate relevant code, or learn conventions. +- **Documentation drafting** - Generating initial drafts of documentation, comments, or commit messages. +- **PR review assistance** - Using AI to help review code, identify potential issues, or suggest improvements. +- **Maintainer-configured review bots** - Automated review bots configured by project maintainers. + +## Contributor Responsibilities + +When using AI tools to assist with contributions, you must: + +1. **Understand every line you submit.** You must be able to independently explain any change in your contribution. "The AI wrote it" is not an acceptable justification during review. + +2. **Review and validate AI output.** Never submit AI-generated content verbatim without careful review. Verify correctness, check for hallucinated APIs or dependencies, and ensure the output follows Cortex conventions. + +3. **Disclose significant AI usage.** If AI generated the bulk of a contribution (e.g., an entire new feature, large refactors, or substantial documentation), note this in the PR description. Minor assistance (autocomplete, small suggestions) does not require disclosure. + +4. **Honour the DCO.** Your `Signed-off-by` line on each commit certifies the [Developer Certificate of Origin](https://developercertificate.org/) for **all** content in that commit, including any AI-generated portions. You are attesting that you have the right to submit the work. + +5. **Meet the same quality bar.** AI-assisted contributions are held to the same standards as any other contribution: tests, documentation, CHANGELOG entries, passing CI, and adherence to the project's [design patterns and conventions](docs/contributing/design-patterns-and-conventions.md). + +## GitHub Communications + +- **Issues, pull request reviews, and discussions** must be substantively human-authored. Do not submit bulk AI-generated comments, reviews, or issue reports. +- Sharing AI-generated analyses (e.g., "I asked an AI to summarise the failure modes and here is what it found") is acceptable when clearly attributed and verified by the contributor. +- Do not use AI tools to generate large volumes of low-quality issues or review comments. + +## Maintainer Authority + +Maintainers may: + +- **Request disclosure** of AI tool usage for any contribution. +- **Close or request revision** of PRs or issues that appear to contain unreviewed AI-generated content. +- **Escalate persistent low-effort submissions** through the project's normal [Code of Conduct](https://github.com/cortexproject/cortex/blob/master/CODE_OF_CONDUCT.md) enforcement process. + +## Relationship to Other Policies + +| Document | Purpose | +|----------|---------| +| [Contributing Guide](CONTRIBUTING.md) | General contribution workflow and requirements | +| [Code of Conduct](https://github.com/cortexproject/cortex/blob/master/CODE_OF_CONDUCT.md) | Community behaviour standards | +| [Governance](GOVERNANCE.md) | Project governance and decision-making | +| [AGENTS.md](AGENTS.md) | Technical guidance **to** AI coding agents working in this repo | + +**AGENTS.md vs GENAI_POLICY.md:** `AGENTS.md` provides instructions that AI coding agents consume when working with the codebase (build commands, architecture, conventions). This document (`GENAI_POLICY.md`) governs how **human contributors** use AI tools when preparing their contributions. + +## References + +- [OpenTelemetry GenAI Contribution Policy](https://github.com/open-telemetry/community/blob/main/docs/how-to-contribute.md#use-of-genai-tools) +- [Linux Foundation AI Guidelines](https://www.linuxfoundation.org/blog/linux-foundation-releases-generative-ai-policy-for-open-source-projects) +- [Developer Certificate of Origin](https://developercertificate.org/) diff --git a/docs/contributing/_index.md b/docs/contributing/_index.md index 1f7b7bb8f5e..93f1c9a6a7f 100644 --- a/docs/contributing/_index.md +++ b/docs/contributing/_index.md @@ -21,6 +21,13 @@ a piece of work is finished it should: * Include a CHANGELOG message if users of Cortex need to hear about what you did. * If you have made any changes to flags or config, run `make doc` and commit the changed files to update the config file documentation. +## Use of AI Tools + +Cortex permits the use of generative AI tools to assist with contributions. Contributors remain +fully responsible for all submitted content. If AI generated the bulk of a contribution, please +disclose this in the PR description. See the full [Generative AI Contribution Policy](/GENAI_POLICY.md) +for details. + ## Formatting Cortex projects uses `goimports` tool (`go get golang.org/x/tools/cmd/goimports` to install) to format the Go files, and sort imports. We use goimports with `-local github.com/cortexproject/cortex` parameter, to put Cortex internal imports into a separate group. We try to keep imports sorted into three groups: imports from standard library, imports of 3rd party packages and internal Cortex imports. Goimports will fix the order, but will keep existing newlines between imports in the groups. We try to avoid extra newlines like that. From e4d4e99b142ef7353f893027504fa95a27cd2266 Mon Sep 17 00:00:00 2001 From: Charlie Le Date: Mon, 6 Apr 2026 09:37:25 -0700 Subject: [PATCH 2/7] Update pull_request_template.md Signed-off-by: Charlie Le --- .github/pull_request_template.md | 1 - 1 file changed, 1 deletion(-) diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index fa5913a75a7..d5c4e33985d 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -13,4 +13,3 @@ Fixes # - [ ] Tests updated - [ ] Documentation added - [ ] `CHANGELOG.md` updated - the order of entries should be `[CHANGE]`, `[FEATURE]`, `[ENHANCEMENT]`, `[BUGFIX]` -- [ ] If AI-assisted: significant AI usage disclosed (see [GenAI Policy](GENAI_POLICY.md)) From 0e6471b48f42a6f9ddd4cef385124616737ef3ef Mon Sep 17 00:00:00 2001 From: Charlie Le Date: Mon, 6 Apr 2026 09:41:13 -0700 Subject: [PATCH 3/7] Update GENAI_POLICY.md Signed-off-by: Charlie Le --- GENAI_POLICY.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/GENAI_POLICY.md b/GENAI_POLICY.md index af5e688b573..da55560ad3f 100644 --- a/GENAI_POLICY.md +++ b/GENAI_POLICY.md @@ -57,6 +57,6 @@ Maintainers may: ## References -- [OpenTelemetry GenAI Contribution Policy](https://github.com/open-telemetry/community/blob/main/docs/how-to-contribute.md#use-of-genai-tools) -- [Linux Foundation AI Guidelines](https://www.linuxfoundation.org/blog/linux-foundation-releases-generative-ai-policy-for-open-source-projects) +- [OpenTelemetry GenAI Contribution Policy](https://github.com/open-telemetry/community/blob/main/policies/genai.md) +- [Linux Foundation AI Guidelines](https://www.linuxfoundation.org/legal/generative-ai) - [Developer Certificate of Origin](https://developercertificate.org/) From af8a9e7acafe0e6e1a0e0a9e4c2ece1d3496c6ab Mon Sep 17 00:00:00 2001 From: Charlie Le Date: Mon, 6 Apr 2026 09:44:04 -0700 Subject: [PATCH 4/7] Update GENAI_POLICY.md Signed-off-by: Charlie Le --- GENAI_POLICY.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/GENAI_POLICY.md b/GENAI_POLICY.md index da55560ad3f..d98462bd16f 100644 --- a/GENAI_POLICY.md +++ b/GENAI_POLICY.md @@ -49,7 +49,7 @@ Maintainers may: | Document | Purpose | |----------|---------| | [Contributing Guide](CONTRIBUTING.md) | General contribution workflow and requirements | -| [Code of Conduct](https://github.com/cortexproject/cortex/blob/master/CODE_OF_CONDUCT.md) | Community behaviour standards | +| [Code of Conduct](code-of-conduct.md) | Community behaviour standards | | [Governance](GOVERNANCE.md) | Project governance and decision-making | | [AGENTS.md](AGENTS.md) | Technical guidance **to** AI coding agents working in this repo | From 8598cb5c327acaa0fe39e47defefb1c3914d6896 Mon Sep 17 00:00:00 2001 From: Charlie Le Date: Mon, 6 Apr 2026 09:46:10 -0700 Subject: [PATCH 5/7] Update GENAI_POLICY.md Signed-off-by: Charlie Le --- GENAI_POLICY.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/GENAI_POLICY.md b/GENAI_POLICY.md index d98462bd16f..45bdc54e75e 100644 --- a/GENAI_POLICY.md +++ b/GENAI_POLICY.md @@ -42,7 +42,7 @@ Maintainers may: - **Request disclosure** of AI tool usage for any contribution. - **Close or request revision** of PRs or issues that appear to contain unreviewed AI-generated content. -- **Escalate persistent low-effort submissions** through the project's normal [Code of Conduct](https://github.com/cortexproject/cortex/blob/master/CODE_OF_CONDUCT.md) enforcement process. +- **Escalate persistent low-effort submissions** through the project's normal [Code of Conduct](code-of-conduct.md) enforcement process. ## Relationship to Other Policies From 8ee09a889c97463799e591c23ed74d42658d2575 Mon Sep 17 00:00:00 2001 From: Charlie Le Date: Mon, 6 Apr 2026 10:47:20 -0700 Subject: [PATCH 6/7] Fix link to Generative AI Contribution Policy Update link to the Generative AI Contribution Policy. Signed-off-by: Charlie Le --- docs/contributing/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing/_index.md b/docs/contributing/_index.md index 93f1c9a6a7f..147cca8ca6b 100644 --- a/docs/contributing/_index.md +++ b/docs/contributing/_index.md @@ -25,7 +25,7 @@ a piece of work is finished it should: Cortex permits the use of generative AI tools to assist with contributions. Contributors remain fully responsible for all submitted content. If AI generated the bulk of a contribution, please -disclose this in the PR description. See the full [Generative AI Contribution Policy](/GENAI_POLICY.md) +disclose this in the PR description. See the full [Generative AI Contribution Policy](../../GENAI_POLICY.md) for details. ## Formatting From 5544fe4eb5cbaab07ae79de4e1be74aaadf58a55 Mon Sep 17 00:00:00 2001 From: Charlie Le Date: Mon, 6 Apr 2026 12:20:46 -0700 Subject: [PATCH 7/7] Fix link formatting in contributing guidelines Updated link formatting for the Generative AI Contribution Policy. Signed-off-by: Charlie Le --- docs/contributing/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/contributing/_index.md b/docs/contributing/_index.md index 147cca8ca6b..ae7cd41f015 100644 --- a/docs/contributing/_index.md +++ b/docs/contributing/_index.md @@ -25,7 +25,7 @@ a piece of work is finished it should: Cortex permits the use of generative AI tools to assist with contributions. Contributors remain fully responsible for all submitted content. If AI generated the bulk of a contribution, please -disclose this in the PR description. See the full [Generative AI Contribution Policy](../../GENAI_POLICY.md) +disclose this in the PR description. See the full `GENAI_POLICY.md` for details. ## Formatting