diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 4ba58c2121..f145ffc938 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -14,6 +14,6 @@ - [ ] AI was used to generate or assist with generating this PR. - + ----- diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 37bbb81a01..cb1a30a4f9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -24,7 +24,7 @@ First time contributing to Homebrew? Read our [Code of Conduct](https://github.c ### "Artificial Intelligence"/Large Language Model (AI/LLM) usage -We allow you to create issues and pull requests with AI/LLM with the following requirements: +We allow you to create issues and pull requests with AI/LLM with the following requirements (see [Responsible AI Usage](https://docs.brew.sh/Responsible-AI-Usage) for the principles behind them): * You must disclose in the initial issue or pull request that you used AI/LLM and what tool/model/etc. you used. * You must review all AI/LLM generated code, prose, etc. content before you ask anyone in Homebrew to review it for you. diff --git a/docs/How-To-Open-a-Homebrew-Pull-Request.md b/docs/How-To-Open-a-Homebrew-Pull-Request.md index ac6b819453..d836311ced 100644 --- a/docs/How-To-Open-a-Homebrew-Pull-Request.md +++ b/docs/How-To-Open-a-Homebrew-Pull-Request.md @@ -144,7 +144,7 @@ Thank you! ### "Artificial Intelligence"/Large Language Model (AI/LLM) usage -We allow you to create issues and pull requests with AI/LLM with the following requirements: +We allow you to create issues and pull requests with AI/LLM with the following requirements (see [Responsible AI Usage](Responsible-AI-Usage.md) for the principles behind them): * You must disclose in the initial issue or pull request that you used AI/LLM and what tool/model/etc. you used. * You must review all AI/LLM generated code, prose, etc. content before you ask anyone in Homebrew to review it for you. diff --git a/docs/Maintainer-Guidelines.md b/docs/Maintainer-Guidelines.md index bdca191000..b206eea3a2 100644 --- a/docs/Maintainer-Guidelines.md +++ b/docs/Maintainer-Guidelines.md @@ -44,6 +44,7 @@ Relatedly: If you don't have time or can't be bothered: you probably don't have the time to review the PR properly. - We're a globally distributed team and this helps us move faster. - The PR review process is primarily a security measure, not a way to get consensus on the perfect code style before merging. +- When reviewing or creating AI-assisted contributions, follow [Responsible AI Usage](Responsible-AI-Usage.md); you are responsible for the output you submit and must review it before asking others to. - It is easy to make changes on a PR after approval, make follow-up PRs to address comments or revert PRs before a tag. - It is (nearly) impossible to merge a PR without approval. - Using `gh pr checkout ` is a super easy way to check out a PR branch using the GitHub CLI. diff --git a/docs/New-Maintainer-Checklist.md b/docs/New-Maintainer-Checklist.md index f002d34255..7ea83e1675 100644 --- a/docs/New-Maintainer-Checklist.md +++ b/docs/New-Maintainer-Checklist.md @@ -56,6 +56,7 @@ A few requests: - If still in doubt please ask for help and we'll help you out. - Please read: - https://docs.brew.sh/Maintainer-Guidelines + - https://docs.brew.sh/Responsible-AI-Usage if you use AI/LLM tools - the team-specific guides linked above and in the maintainer guidelines - anything else you haven't read on https://docs.brew.sh diff --git a/docs/Responsible-AI-Usage.md b/docs/Responsible-AI-Usage.md new file mode 100644 index 0000000000..5c260fd33b --- /dev/null +++ b/docs/Responsible-AI-Usage.md @@ -0,0 +1,65 @@ +--- +last_review_date: "2026-06-10" +--- + +# Responsible AI Usage + +This guide is for maintainers and contributors who use "Artificial Intelligence"/Large Language Model (AI/LLM) tools when working on Homebrew. +It expands on the [AI/LLM usage rules in our Contributing guide](https://github.com/Homebrew/brew/blob/HEAD/CONTRIBUTING.md) and the repository's `AGENTS.md` files with the principles we expect you to apply. + +AI tools can make you faster. +They can also produce confidently plausible but wrong output. +These guidelines exist to make Homebrew better rather than shifting work and risk onto other maintainers. + +## Human in the loop + +AI is not responsible for its output: you are responsible for the output of the AI tools you use. +A pull request with your name on it is your work regardless of how much of it an AI wrote. + +Verify AI output for correctness as you would that of an avatarless GitHub user with no previous contributions. +Read it, run it, test it and make sure you understand it. + +Do not ask other humans to review your AI-generated code until you have reviewed it yourself. +This is already a requirement in our [Contributing guide](https://github.com/Homebrew/brew/blob/HEAD/CONTRIBUTING.md): you must review all AI/LLM-generated content before asking anyone in Homebrew to review it, and you must be able to address all review comments yourself even when the AI cannot. + +As the [pull request template](https://github.com/Homebrew/brew/blob/HEAD/.github/PULL_REQUEST_TEMPLATE.md) sets out, disclose when AI was used to generate or assist with a pull request and explain how you verified the changes. + +## Trust appropriately + +AI tools should not be trusted much more or much less than those of humans. +Treat their output as a fallible first draft. + +Verify output: it may be wrong. +Where Homebrew has fast feedback loops, use them. +Run `brew lgtm` (style, typechecking and tests) on every change, and read the diff with `git diff` to keep it small and intentional. + +Review code, but don't try to make all of it perfectly match how you would have written it by hand. +Reviewing for correctness, security and maintainability matters far more than reviewing for personal style; our [Prose Style Guidelines](Prose-Style-Guidelines.md) and RuboCop already cover most of the latter. + +Review mission-critical code, such as anything touching installation, security, package downloads or the `Formula` and `Cask` DSLs, much more carefully than a one-off script you run locally (which may not need much review at all). + +## Use AI to improve AI + +For maintainers or regular contributors, when prompting an AI requires repeated corrections and nudges to get Homebrew conventions right, ask it to write or update an `AGENTS.md` file so the next person and the next agent start from a better place. +We already keep instructions in `AGENTS.md` at the repository root. + +It's acceptable to do this in the same pull request as your 3rd or later PR. +Don't do this on your first. + +## Try things + +LLM technologies are changing month by month. +Don't assume a tool you tried last month or last year is still as good or as bad as it was then. + +AI use is a new skill and you will be bad at it initially. +Start on areas where the learning curve is lower and the impact is higher, get better and then take on harder problems. + +Experiment with your setup as well as your prompts. +Running agents in sandboxed git worktrees, for example, lets you give them more autonomy while containing the blast radius; see Mike McQuaid's write-up of [sandboxed agent worktrees](https://mikemcquaid.com/sandboxed-agent-worktrees-my-coding-and-ai-setup-in-2026/) for one such approach. + +## See also + +- [Contributing to Homebrew](https://github.com/Homebrew/brew/blob/HEAD/CONTRIBUTING.md) +- [Maintainer Guidelines](Maintainer-Guidelines.md) +- [Maintainers: Avoiding Burnout](Maintainers-Avoiding-Burnout.md) +- [Prose Style Guidelines](Prose-Style-Guidelines.md) diff --git a/docs/index.md b/docs/index.md index 57b9eea4f6..52efdda2f5 100644 --- a/docs/index.md +++ b/docs/index.md @@ -51,6 +51,7 @@ Documentation is grouped below by audience: users, contributors, maintainers and ## Contributors - [How to Open a Pull Request (and get it merged)](How-To-Open-a-Homebrew-Pull-Request.md) +- [Responsible AI Usage](Responsible-AI-Usage.md) - [Working with Homebrew as an Upstream Project](Working-with-Homebrew-as-an-Upstream-Project.md) - [Formula Cookbook](Formula-Cookbook.md) - [Cask Cookbook](Cask-Cookbook.md)