|
| 1 | +# AI contribution policies |
| 2 | + |
| 3 | +This document contains Flutter's policies around the use of AI assistants or |
| 4 | +agents when contributing to Flutter. We expect both humans and AI agents to |
| 5 | +follow the letter and spirit of these policies. If contributors notice behaviors |
| 6 | +that are not aligned with these policies, they should contact |
| 7 | + |
| 8 | + |
| 9 | +## Philosophy |
| 10 | + |
| 11 | +A common question in discussions around AI policies for open source projects is: |
| 12 | +"Why have an AI policy at all? Why does it matter how the code was created; |
| 13 | +shouldn't the code speak for itself?" |
| 14 | + |
| 15 | +In general, we agree, which is why our policy focuses on behaviors rather than |
| 16 | +tools. The behaviors that led to the creation of this policy are problematic |
| 17 | +regardless of whether they are AI-generated or human-generated. However, it is |
| 18 | +useful to highlight these policies in the context of AI because we have seen |
| 19 | +that these behaviors are orders of magnitude more common when AI is involved. |
| 20 | +For example: |
| 21 | + |
| 22 | +* Submitting a PR containing hundreds of lines of code that the contributor |
| 23 | + doesn't understand is always a problem. This was rare before the widespread |
| 24 | + use of AI agents, but is more common with AI-assisted development. |
| 25 | +* Having several rounds of exchanges where a reviewer asks for a change, and the |
| 26 | + contributor says that they have made that change but haven't, is always a |
| 27 | + waste of reviewer time. It's very rare for a contributor to deliberately and |
| 28 | + obviously lie to a reviewer, but unfortunately common for contributors to |
| 29 | + uncritically repeat AI agent hallucinations. |
| 30 | +* Contributions that ignore our process have always been problematic, because |
| 31 | + standardizing the process is an important part of how we keep our triage and |
| 32 | + review load manageable. However, a contributor who has spent hours or days on |
| 33 | + a PR is much more likely to take some time to learn and follow our process to |
| 34 | + avoid having that effort be wasted than someone who spent a few minutes |
| 35 | + generating the PR. |
| 36 | + |
| 37 | +Overall, regardless of the forum and whether by way of automation or manual |
| 38 | +unedited copy-and-paste, do not use AI to substitute for human discussion. |
| 39 | + |
| 40 | +## Our CLA |
| 41 | + |
| 42 | +All submissions to Google Open Source projects need to follow |
| 43 | +[Google's Contributor License Agreement (CLA)](https://cla.developers.google.com/), |
| 44 | +in which contributors agree that their contribution is an original work of |
| 45 | +authorship. This does not prohibit the use of coding assistance tools, but what |
| 46 | +is submitted needs to be the contributor's original creation. |
| 47 | + |
| 48 | +## Issues and triage |
| 49 | + |
| 50 | +Comments and reports in the issue database should add value (see |
| 51 | +[issue hygiene](./docs/contributing/issue_hygiene/README.md) and the |
| 52 | +[triage guide](./docs/triage/README.md)). Anyone can easily feed an issue URL |
| 53 | +into an agent, so just posting the results of doing that is generally not |
| 54 | +helpful. |
| 55 | + |
| 56 | +* **Do not** run an unsupervised agent that posts triage comments to the issue |
| 57 | + database. Any automated agent needs to be approved in advance, after |
| 58 | + discussion with the Flutter team. |
| 59 | +* Use AI tools to help you contribute to an issue rather than as replacements |
| 60 | + for your contribution. AI tools may be helpful for specific tasks, such as |
| 61 | + creating reduced test cases or identifying potential duplicate issues, but you |
| 62 | + must verify their output. For example, if you use an AI tool to create a |
| 63 | + reduced test case, make sure that you can actually reproduce the issue before |
| 64 | + posting it. |
| 65 | +* Reproducible and concise issues respect maintainers' time. AI-generated output |
| 66 | + is often too verbose, inaccurate, and difficult to triage. You likely must |
| 67 | + **edit AI-generated text** to improve readability and focus on what is |
| 68 | + important. |
| 69 | + |
| 70 | +## Pull requests |
| 71 | + |
| 72 | +PRs prepared using AI tools must follow the standard |
| 73 | +[tree hygiene](./docs/contributing/Tree-hygiene.md) process and the |
| 74 | +[style guide](./docs/contributing/Style-guide-for-Flutter-repo.md), along with |
| 75 | +these requirements: |
| 76 | + |
| 77 | +1. You must review all AI-generated code before opening a (non-draft) PR, and |
| 78 | + before requesting re-review of any updates to the PR. |
| 79 | + * You are responsible for making sure that code you submit meets the Flutter |
| 80 | + project's standards. |
| 81 | + * Unmodified AI output generally does not meet those standards. |
| 82 | +1. You must understand and be able to discuss the code in the PR. |
| 83 | + * Non-trivial PRs require discussion and iteration during review. If you do |
| 84 | + not understand the code, you cannot meaningfully respond to review |
| 85 | + feedback. |
| 86 | + * In our experience, simply feeding review feedback into an AI agent and |
| 87 | + uncritically reposting its output will not lead to a constructive review. |
| 88 | +1. You must verify the accuracy of any AI-generated text you include in the PR |
| 89 | + description or review discussion comments. |
| 90 | + * If an AI provides you incorrect information, it is just hallucinating; if |
| 91 | + you choose to paste that text into GitHub, you are misrepresenting your PR |
| 92 | + to your reviewer. |
| 93 | + * In particular, do not tell a reviewer that you have addressed their |
| 94 | + feedback just because AI output says so. It is your responsibility to make |
| 95 | + sure that review feedback has actually been addressed. |
| 96 | + |
| 97 | +### Reviewer guidelines |
| 98 | + |
| 99 | +Because the Flutter team's time is limited, and the capacity for people outside |
| 100 | +the team to generate plausible-looking code is unlimited, be mindful as a |
| 101 | +reviewer about what code you choose to review. Consider immediately closing PRs |
| 102 | +that have any of the following red flags: |
| 103 | + |
| 104 | +* The PR description has entirely replaced our template with AI-generated |
| 105 | + output, and the PR is missing at least one obvious checklist item (tests, |
| 106 | + issue link, etc.). |
| 107 | + * If the contributor did not follow our process from the outset, they are |
| 108 | + unlikely to understand what is expected of them during review. |
| 109 | +* The PR description does not match the changes. |
| 110 | + * If the contributor did not review both the changes and the description |
| 111 | + enough to notice this, they have not followed the AI contribution policy. |
| 112 | +* The PR contains irrelevant AI-generated files, such as agent planning `.md` |
| 113 | + files. |
| 114 | + * If the contributor did not review the changes enough to notice and remove |
| 115 | + these files, they have not followed the AI contribution policy. |
| 116 | + |
| 117 | +As always when closing a PR, explain why and provide next steps. In the case |
| 118 | +that the PR is closed for failing to follow our AI policies, the next steps |
| 119 | +would include linking to this document. |
| 120 | + |
| 121 | +As a guiding principle, if at any point in the process you feel that you are |
| 122 | +getting unfiltered or minimally filtered AI output as code and/or comment |
| 123 | +responses, ask yourself: |
| 124 | + |
| 125 | +* If this PR weren't here, would I choose to spend my time fixing this issue? |
| 126 | +* Would I choose to fix it using an AI agent that took hours or days to respond |
| 127 | + to every prompt? |
| 128 | + |
| 129 | +Unless the answer to both questions is yes, the review is not a good use of your |
| 130 | +time. |
| 131 | + |
| 132 | +This applies even if you are multiple rounds into the review: if the contributor |
| 133 | +closed the PR, would you take it over using an extremely high-latency agent? |
| 134 | +Beware the sunk cost fallacy. |
0 commit comments