Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).
2 changes: 2 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -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).
62 changes: 62 additions & 0 deletions GENAI_POLICY.md
Original file line number Diff line number Diff line change
@@ -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](code-of-conduct.md) enforcement process.

## Relationship to Other Policies

| Document | Purpose |
|----------|---------|
| [Contributing Guide](CONTRIBUTING.md) | General contribution workflow and requirements |
| [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 |

**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/policies/genai.md)
- [Linux Foundation AI Guidelines](https://www.linuxfoundation.org/legal/generative-ai)
- [Developer Certificate of Origin](https://developercertificate.org/)
7 changes: 7 additions & 0 deletions docs/contributing/_index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 `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.
Expand Down
Loading