|
| 1 | +# Contributing |
| 2 | + |
| 3 | +This document defines shared contribution rules for GrapheneOS repositories. |
| 4 | +Repository-specific rules may add stricter requirements. |
| 5 | + |
| 6 | +## Before Writing Code |
| 7 | + |
| 8 | +Do not start implementing a new feature without first consulting with the |
| 9 | +GrapheneOS team and discussing the proposal in the relevant GitHub issue. |
| 10 | + |
| 11 | +The same applies to large bug fixes, behavior changes, migrations, rewrites, |
| 12 | +dependency changes, SDK/target SDK changes, permission changes, storage changes, |
| 13 | +or anything with compatibility, privacy, security, UX, or maintenance impact. |
| 14 | + |
| 15 | +For this work, open or use an existing GitHub issue and make sure the expected |
| 16 | +direction is clear before implementing. A pull request should be the result of |
| 17 | +an agreed direction, not the first place where a feature or large bug fix is proposed. |
| 18 | + |
| 19 | +Small, obvious, tightly scoped bug fixes may be submitted directly when the |
| 20 | +problem and fix are clear. If there is any uncertainty about desired behavior, |
| 21 | +compatibility, or project direction, discuss it first. |
| 22 | + |
| 23 | +Pull requests ignoring this coordination requirement will be **closed without review**. |
| 24 | + |
| 25 | +## AI-Assisted Contributions |
| 26 | + |
| 27 | +AI tools may be used as assistants. They may not be used as a substitute for |
| 28 | +understanding, design work, manual review, testing, or ownership. |
| 29 | + |
| 30 | +Do not submit AI output you do not fully understand. This is prohibited. |
| 31 | + |
| 32 | +Maintainers can easily identify pull requests that are fully AI-written. |
| 33 | +Do not assume this can be hidden. |
| 34 | + |
| 35 | +Do not submit AI-assisted pull requests for parts of GrapheneOS you do not deeply understand. |
| 36 | +Deep understanding of the subject area is required before using AI to write code for it. |
| 37 | + |
| 38 | +Before submitting AI-assisted work, you must manually review the complete diff |
| 39 | +and be able to explain: |
| 40 | + |
| 41 | +- what changed and why |
| 42 | +- the important control flow, data flow, state changes, and error paths |
| 43 | +- the security, privacy, permission, storage, lifecycle, and compatibility implications |
| 44 | +- why each dependency, abstraction, API, and test was added or changed |
| 45 | +- why the implementation is appropriate for this repository |
| 46 | +- what alternatives were rejected and why |
| 47 | + |
| 48 | +Reviewing generated code by asking another AI model is not manual review. |
| 49 | +A passing build is not proof that the code is correct. |
| 50 | +A generated PR description is not proof that the contributor understands the change. |
| 51 | + |
| 52 | +## Unacceptable AI-Generated Submissions |
| 53 | + |
| 54 | +Low-quality AI-generated submissions are not accepted. |
| 55 | +Pull requests will be closed without review when they show signs that the author did not understand, |
| 56 | +review, or test the change. |
| 57 | + |
| 58 | +AI patterns are easy to detect. |
| 59 | +If they appear in a pull request, maintainers will close it instead of spending review time proving |
| 60 | +that it was generated or explaining each problem. |
| 61 | + |
| 62 | +Repeated low-quality AI-generated submissions may lead maintainers to stop reviewing further pull |
| 63 | +requests from the same contributor. |
| 64 | + |
| 65 | +See [ai/llm-usage-guidelines.md](ai/llm-usage-guidelines.md) for the full AI |
| 66 | +usage policy. |
| 67 | + |
| 68 | +## Pull Request Expectations |
| 69 | + |
| 70 | +Before opening a pull request: |
| 71 | + |
| 72 | +- make sure the scope was discussed first when required |
| 73 | +- keep the change focused and reviewable |
| 74 | +- preserve existing user-visible behavior unless the change was agreed |
| 75 | +- follow [guidelines/](guidelines/) for app architecture, code style, and |
| 76 | + testing guidance |
| 77 | +- add or update tests for changed behavior |
| 78 | +- cover happy paths, unhappy paths, edge cases, and regressions |
| 79 | +- run the relevant build, static-analysis, unit-test, and coverage checks |
| 80 | +- manually review the full diff |
| 81 | +- write the pull request description in your own words |
| 82 | + |
| 83 | +The pull request description should include: |
| 84 | + |
| 85 | +- the linked issue or discussion |
| 86 | +- what changed |
| 87 | +- why the change is needed |
| 88 | +- how it was tested, including exact commands when relevant |
| 89 | +- compatibility, privacy, security, migration, or UX risks |
| 90 | +- any checks that were not run and why |
| 91 | +- any remaining limitations or follow-up work |
| 92 | + |
| 93 | +Do not hide uncertainty. If part of the behavior is unclear, say so and ask for |
| 94 | +guidance before expanding the implementation. |
0 commit comments