diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 00e87ff8ea..fb189ac287 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,6 +1,44 @@ -**What I did** +## What This PR Does -**Related issue** - + + +## Related Issue + + + +Fixes # + +## Changes Made + + + +- +- +- + +## Testing Done + + + +- [ ] Unit tests pass: `make test` +- [ ] E2E tests pass: `make e2e-compose` or `make e2e-compose-standalone` +- [ ] Linting passes: `make lint` +- [ ] Code formatted: `make fmt` +- [ ] Manually tested (describe): +- [ ] I've reviewed the code myself and removed `AI_AGENT_DISCLOSURE.md` if my agent added it + +## AI Tool Used (if applicable) + + + + +AI Tool: + +## Additional Context + + **(not mandatory) A picture of a cute animal, if possible in relation to what you did** diff --git a/AGENTS.md b/AGENTS.md index e91c95f52a..becfc581da 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,5 +1,7 @@ # Project: Docker Compose +All agents must conform to [AI_POLICY.md](AI_POLICY.md). + ## Build & Test - Build: `make build` diff --git a/AI_POLICY.md b/AI_POLICY.md new file mode 100644 index 0000000000..09a5a975f5 --- /dev/null +++ b/AI_POLICY.md @@ -0,0 +1,87 @@ +# AI Usage Policy + +Docker Compose has clear rules for AI-assisted contributions: + +- **All AI usage in any form must be disclosed.** You must state + the tool you used (e.g. GitHub Copilot, Claude Code, Cursor, ChatGPT) + along with the extent that the work was AI-assisted. + +- **If your AI agent created an `AI_AGENT_DISCLOSURE.md` file for you, that's + a checkpoint, not something to merge.** It states the change may not have + been independently reviewed or tested yet. Review the code yourself, then + remove the file before opening the PR. An automated check blocks merging + while it's present, precisely so this step can't be skipped. + +- **Pull requests created in any way by AI can only be for approved issues.** + Only submit PRs for issues labeled `status/approved` by a maintainer. + Drive-by pull requests that do not reference an existing issue, or reference + issues not yet approved (e.g., `status/0-triage`), will be closed. If AI + isn't disclosed but a maintainer suspects its use, the PR will be closed. + If you want to work on an issue, wait for maintainer approval first. + +- **Pull requests created by AI must have been fully verified with + human testing.** AI must not create hypothetically correct code that + hasn't been tested. You must be able to explain every line of the + change yourself. You must run `make test`, `make lint`, and relevant + E2E tests locally. Importantly, you must not allow AI to write + code for platforms or environments you don't have access to manually + test on. + +- **Code must follow Docker Compose's existing patterns.** Before writing + code, read [AGENTS.md](AGENTS.md) and search for similar functionality + in the codebase. AI-generated code that ignores project conventions + (error handling, logging, testing patterns) will be rejected. Run + `make fmt` before submitting. + +- **Issues and discussions can use AI assistance but must have a full + human-in-the-loop.** This means that any content generated with AI + must have been reviewed _and edited_ by a human before submission. + AI is very good at being overly verbose and including noise that + distracts from the main point. Humans must do their research and + trim this down. + +- **A merged contribution is not a one-shot event.** If your change surfaces + a regression, a follow-up review comment, or a question after merge, we + expect you to engage - fix it, or help us understand it. Landing a PR to + add a line to an open-source portfolio, with no intention of following up, + is not the kind of contribution we're looking for. + +- **Contributors who repeatedly ignore this policy will have PRs closed + and may be banned from the repository.** We welcome developers at all + skill levels and are happy to help you learn. But if you're learning, + we encourage you to write code yourself rather than relying on AI—we'll + provide better feedback that way. + +These rules apply to all outside contributions. Maintainers may use AI +tools at their discretion, applying the judgment earned through their +contributions to the project. + +## There are Humans Here + +Please remember that Docker Compose is maintained by humans. + +Every discussion, issue, and pull request is read and reviewed by +humans. It is a point of interaction between people and their work. +Approaching this with low-effort, unverified submissions is disrespectful +and puts the burden of validation on maintainers who volunteer their time. + +In a perfect world, AI would produce high-quality, correct code every time. +But that reality depends on the person using the AI. Today, we see too many +contributions where AI-generated code hasn't been tested, doesn't follow +project patterns, or solves problems that don't exist. Until this improves, +we need clear rules to protect maintainer time. + +## AI is Welcome Here + +Docker Compose is developed with AI assistance, and many maintainers use +AI tools productively in their workflow. As a project, we welcome AI as +a tool for those who use it responsibly! + +**Our reason for this policy is not an anti-AI stance**, but rather a +response to the increase in low-quality AI-generated pull requests that +don't address real user needs or follow project standards. It's about +the quality of contributions, not the tools used to create them. + +This section exists to be transparent about the project's use of AI and +to clarify that this policy targets contribution quality, not the use +of AI tools themselves. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 573e7e8064..4e598623bd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -16,6 +16,7 @@ start participating. - [Reporting security issues](#reporting-security-issues) - [Reporting other issues](#reporting-other-issues) - [Quick contribution tips and guidelines](#quick-contribution-tips-and-guidelines) + - [AI-assisted contributions](#ai-assisted-contributions) - [Pull requests are always welcome](#pull-requests-are-always-welcome) - [Talking to other Docker users and contributors](#talking-to-other-docker-users-and-contributors) - [Conventions](#conventions) @@ -66,7 +67,7 @@ When sending lengthy log files, consider posting them as a gist Don't forget to remove sensitive data from your log files before posting (you can replace those parts with "REDACTED"). -_Note:_ +_Note:_ Maintainers might request additional information to diagnose an issue, if initial reporter doesn't answer within a reasonable delay (a few weeks), issue will be closed. @@ -75,6 +76,25 @@ issue will be closed. This section gives the experienced contributor some tips and guidelines. +### AI-assisted contributions + +Docker Compose has clear rules for AI-assisted contributions. **Read the full policy**: [AI_POLICY.md](AI_POLICY.md) + +**Required for all AI-assisted PRs**: +- **Disclose** the AI tool used (GitHub Copilot, Claude Code, ChatGPT, Cursor, etc.) +- **Link to an approved issue** - only submit PRs for issues labeled `status/approved` +- **Test thoroughly** - run `make test`, `make lint`, and relevant E2E tests +- **Follow existing patterns** - read [AGENTS.md](AGENTS.md) and match nearby code +- **Understand your code** - you must be able to explain every line +- **Stick around** - a merge isn't the finish line; follow up on review comments + and fix regressions afterwards + +**PRs that don't follow these rules will be closed.** Contributors who repeatedly +ignore this policy may be banned from the repository. + +This is not an anti-AI stance - we use AI ourselves. This policy exists to maintain +code quality and protect maintainer time. See [AI_POLICY.md](AI_POLICY.md) for details. + ### Pull requests are always welcome Not sure if that typo is worth a pull request? Found a bug and know how to fix @@ -151,7 +171,9 @@ run `golangci-lint run ./...` or `make lint` before committing. Most editors have plug-ins that apply formatting automatically. Pull request descriptions should be as clear as possible and include a reference -to all the issues that they address. +to all the issues that they address. Explain both **what** changed and **why** +the change was necessary. If you used AI assistance, include a disclosure +(see [AI_POLICY.md](AI_POLICY.md)). We recommend following the [conventional commits](https://www.conventionalcommits.org/) format (`type(scope): summary`, e.g. `fix(watch): handle symlinked directories`)