Add the new AI contribution policy

2026-10-01 06:08:11 +08:00 · 2026-01-05 17:03:42 -08:00
parent 2a59bd50bd
commit 4f4ec7ffff
10 changed files with 94 additions and 35 deletions
@@ -7,9 +7,9 @@ page_template = "book.html"
 order = 3 # Chapter number
 +++

-There are two places to look for beginner-friendly development tasks. Usually, the best option is to select one of the many bite-sized task descriptions marked with a ‼️ reaction in the `#✅code-todo-list` channel of the [Discord server](https://discord.graphite.art). You may also browse the [task board](https://github.com/orgs/GraphiteEditor/projects/1/views/1), which lists [beginner issues](https://github.com/orgs/GraphiteEditor/projects/1/views/6) to pick from. The Discord option usually has the more approachable tasks compared to the GitHub issues, which tend to have more variability in complexity.
+There are two places to look for beginner-friendly development tasks. Usually, the best option is to select one of the many bite-sized task descriptions marked with a ‼️ reaction in the `#✅code-todo-list` channel of the [Discord server](https://discord.graphite.art). You may also browse the task board for a list of [beginner issues](https://github.com/orgs/GraphiteEditor/projects/1/views/6) to pick from. The Discord option usually has the more approachable tasks, compared to the GitHub issues that often have more variability in complexity.

-If you're unsure about which task to pick, feel free to ask in the `#📄development` channel.
+If you're unsure about which task to pick, feel free to ask in the `#📄development` channel. You can also use that channel to ask for coding help if you anticipate it will be a quick discussion rather than a longer-running conversation that deserves its own thread.

 You may right click a `#✅code-todo-list` task and select "Create Thread" to ask questions and discuss your development progress. If your work doesn't correspond to a specific listed task in that channel, you can also create a thread in `#🧵task-help` with a short, descriptive title ending with your issue or PR number.

@@ -0,0 +1,23 @@
+++
+title = "AI contribution policy"
+
+[extra]
+order = 4 # Page number after chapter intro
+++
+
+Many open source projects including Graphite have begun to be spammed with an ever-increasing flood of low-quality PRs written partly or wholly by AI. These harm the project by wasting the time of maintainers and preventing PRs by genuine contributors from receiving timely review. We aim to be reasonable and understanding to contributors who put in the effort, but it has become necessary to set some strict rules against low-effort PRs.
+
+## Acceptable usage
+
+- Non-agent AI tools may **assist** with debugging and tab-completion of single lines of code you would have otherwise written yourself. This does not require disclosure.
+- AI chat tools (not agents) may help you **generate** small (sub-40 line) snippets of code that you manually copy and paste, provided that you carefully review every line to ensure it is consistent with how you would have written it yourself. This requires disclosure.
+
+## Unacceptable usage
+
+- AI slop, "vibe-coded", or agent-written PRs are strictly forbidden and may be treated as malicious spam attacks against the project, resulting in a ban.
+- PR description text and replies to reviewers must be written by you, not AI. If your English is imperfect, just try your best; it is better than AI babble.
+
+## Required disclosure
+
+- Graphite has **zero-tolerance** for contributing undisclosed AI-generated content.
+- A detailed, human-written description must accompany every line of material that you did not personally write using your own brain. It should justify why each line is correct and appropriate. This should be prepared ahead of time and written as self-review comments on the GitHub PR's diff immediately after the PR is opened or new code is pushed.
@@ -9,7 +9,7 @@ The Graphite project prizes code quality and accessibility to new contributors.

 ## Linting

-Please ensure Clippy is enabled. This should be set up automatically in VS Code. Try to avoid committing code with lint warnings. You may execute `cargo clippy` anytime to confirm.
+Please ensure Clippy is enabled. This should be set up automatically in VS Code. Avoid committing code with lint warnings so the code review process goes smoothly. You may execute `cargo clippy` anytime to confirm.

 ## Naming

@@ -29,7 +29,7 @@ Always use the style `42.` instead of `42.0` for whole-number floats to maintain

 For consistency, please try to write comments (`//`) in *Sentence case* (with a capital first letter) and don't end with a period unless multiple sentences are used in the same comment. For doc comments (`///`), always end your sentences with a period. There should always be one space after the `//` or `///` comment markers, and `/* */` style comments should be avoided.

-Avoid including commented-out code, unless you have a compelling reason to keep it around for future adaption, in your PRs that are open for code review.
+Avoid including commented-out code in PRs that are open for code review unless you have a compelling reason to keep it around for future reference.

 Comments should usually be placed on a separate line above the code they are referring to, not at the end of the same code line.

@@ -37,7 +37,7 @@ Comments should usually be placed on a separate line above the code they are ref

 Please make a habit of grouping together related lines of code in blocks separated by blank lines. These are like your paragraphs if you were writing a novel — they greatly aid readability and your copy editor would have significant concerns with your writing if they were absent.

-If you have dozens of lines comprising a single unbroken block of logic, you are likely not splitting it apart enough to aid readability. Find sensible places to partition the logic and insert blank lines between each. Roughly 10% of the code you write should ideally be blank lines, otherwise you are likely underutilizing them at the expense of readability.
+If you have dozens of lines comprising a single unbroken block of logic, you are likely not splitting it apart enough to aid readability. Find sensible places to partition the logic and insert blank lines between each. At least 10% of the code you write should ideally be blank lines, otherwise you are likely underutilizing them at the expense of readability.

 ## Imports

@@ -9,13 +9,17 @@ Collaboration is a key part of real-world software engineering. Graphite follows

 This assumes you understand enough about how Git works to utilize commits, branches, and multiple remotes. If you're new to Git, you will need to learn those topics on your own, but a good starting point is [this portion](https://youtu.be/vUzIeg8frh4?t=237) of the Graphite intro webcast which recommends installing the [Git Graph](https://marketplace.visualstudio.com/items?itemName=mhutchie.git-graph) extension for VS Code to visualize your Git history and branches.

+## AI usage
+
+If you are using any form of AI tools in your development workflow, you must read and comply with our [AI contribution policy](../ai-contribution-policy) before submitting your PR.
+
 ## Git branch name

 Before making your first commit, create a new branch with a name that describes what it's about. Aim for short but sufficiently descriptive. Kebab-case (using hyphens between words) is our usual convention. Don't include a prefix like `feature/` or `fix/` which just adds visual noise. An example like `fix-path-tool-selection-history` is fine, but almost too long.

-Rename it if you already made a branch with a different name. Create a new branch if you've been committing to `master` or another existing branch. If your branch is specifically called `master`, it becomes harder to work with during code reviews.
+**Warning: do not open a PR from a branch named `master`.** It makes code review considerably more difficult. Create a new branch if you've already been committing to `master` and open your PR from that correctly-named branch.

-After you push your branch to GitHub then open a PR, you won't be able to change its name. But please don't close a PR and open a new one just because the branch name isn't optimal. Just keep these tips in mind for the next time.
+After you push your branch to GitHub then open a PR, you won't be able to change its branch name. But please don't close a PR and open a new one just because the branch name isn't optimal. Just keep these tips in mind for the next time.

 ## Pull request

@@ -23,7 +27,7 @@ Once you have gotten your code far enough along that you are confident you'll be

 Later on when you are building larger features, a PR should be opened once you have meaningful progress. That way, it can be kept safe on GitHub and other maintainers can check in to see your status so your work is less of a mystery.

-Here's the important part: when you open a PR, it should be marked as a draft unless it is currently ready for review. The left image shows how to open a new PR as a draft, and the right image shows how to convert an existing PR to a draft.
+**Here's the important part:** when you open a PR, it should be marked as a draft unless it is currently ready for review. The left image shows how to open a new PR as a draft, and the right image shows how to convert an existing PR to a draft.

 <p><img src="https://static.graphite.art/content/volunteer/guide/draft-pr.avif" onerror="this.onerror = null; this.src = this.src.replace('.avif', '.png')" alt="Screenhots showing GitHub's &quot;Create pull request (arrow) > Create draft pull request&quot; and &quot;Still in progress? Convert to draft&quot; buttons" /></p>

@@ -45,7 +49,7 @@ As a bonus, it can be helpful for maintainers if you take a few minutes to write

 If you have concerns about a certain approach you took or if a certain part of your code is as clean as it could be, you can leave comments on lines of your own code from the "Files changed" tab after opening the PR.

-## Comment on the issue
+## Comment on the issue for assignment after it merges

 For any issue referenced in your PR (including tracking issues), we need you to leave a comment on issue. It doesn't matter what you write. You can just say "I opened PR #456" or something to that effect. This is only necessary because we will need to assign that issue to you upon merging your PR, but GitHub only allows assignments to those who have commented.

@@ -55,7 +59,7 @@ We don't commonly assign issues while a PR is still in progress, only upon landi

 ## Code review etiquette

-It is your responsibility to build the editor, thoroughly test your work, and employ common sense to avoid wasting a maintainer's time in needing to point out obvious flaws. It is not uncommon for inexperienced contributors to request review when their code entirely fails to implement the task at hand, or breaks surrounding functionality in a way that should have been immediately apparent. This doesn't leave a good impression and can frustrate maintainers.
+It is your responsibility to build the editor, thoroughly test your work, and employ common sense to avoid wasting a maintainer's time in needing to point out obvious flaws. It is not uncommon for inexperienced contributors to request review when their code entirely fails to implement the task at hand, or breaks surrounding functionality in a way that should have been immediately apparent. This doesn't leave a good impression and can frustrate maintainers. It may also be interpreted as AI-generated spam if the mistakes are egregious enough, which will lead to a ban according to our [AI contribution policy](../ai-contribution-policy).

 If you don't actually understand what is intended with your feature/fix and why this is meaningful to a user of Graphite, spend time becoming that user and understanding the context. [Learning](/learn) at least the basics of using Graphite is important. Then ask questions in Discord if you're still confused about specific edge cases or the wording of the task.

@@ -65,13 +69,15 @@ It is also common for larger tasks to enter a round of review to confirm the dir

 Before marking your PR as ready for review, you should do a self-review. That means reading over the diff of all your changes to ensure they are correct, complete, and lacking frivolous changes like unintended whitespace alterations, leftover debugging code, or commented-out lines. Read over it with a fine-toothed comb so maintainers don't have to nitpick as much. It is only fair that your first code reviewer should be yourself, so you catch the obvious flaws first.

+Feel free to leave comments on lines of your own code in the diff if you want to communicate concerns or highlight uncertainties to the maintainer. This is also where you must [disclose AI generated lines of code](../ai-contribution-policy) if applicable.
+
 ## Passing CI

 Upon pushing a commit to your PR's branch, CI will need to build and test your code. PRs from forks will have to wait until a maintainer approves the CI run. If you're uncertain, run `cargo test --all-features` on your machine or ask a maintainer to trigger CI for you.

-You also have to pass `cargo fmt` and `cargo clippy` locally before your PR can be merged.
+You also have to pass `cargo fmt` and `cargo clippy` in CI before your PR can be merged. You should run these commands locally before pushing to confirm.

-Your goal is for the check called "Editor: Dev & CI / build (pull_request)" to pass with a ✅. If it fails with a ❌, you will need to investigate. If you need access to the build logs, ask a maintainer to provide them. Occasionally, other checks may fail, but you likely won't be responsible for fixing those and they can be ignored.
+Your goal is for the check called "Editor: Dev & CI / build (pull_request)" to pass with a ✅. If it fails with an ❌, you will need to investigate. If you need access to the build logs, ask a maintainer to provide them. Occasionally, other checks may fail, but you likely won't be responsible for fixing those and they can be ignored.

 ## Keeping your work up-to-date

@@ -85,6 +91,8 @@ When your branch can be updated with `master` without conflicts, you can click t

 Be sure to pull the rebased, or updated-with-a-merge-commit, branch after you or a maintainer updates it (or pushes other commits to it) to ensure you are working on the latest code.

+**Please do not** constantly rebase or merge every day while you're waiting for review since it's unhelpful and gets annoying. A reviewer will do that for you if there are no conflicts. But if there are conflicts, you *will* need to resolve them and push the updated code before review.
+
 ## Review process

 Assuming you have done what's explained above, a maintainer will aim to review your PR within a few days if possible. Feel free to send reminders because PRs can get overlooked.
@@ -96,11 +104,11 @@ There are two parts to the review process, QA and code review, which occur separ
 - Quality assurance (QA): A build of your code will be opened and tested to ensure it implements the requested functionality and doesn't introduce regressions. This is not a substitute for your own testing, but it is a necessary line of defense against overlooked issues. This is usually performed by Keavon, the founder and product designer, whose eye for detail keeps the app polished and consistent. Maintainers (and only maintainers) have the ability to invoke CI by commenting "!build" on your PR which will produce a build link. That is a unique link hosting a build of your PR's current code.
 - Code review: The code will be checked for flawed approaches, pitfalls, confusing logic, [style guide](../code-quality-guidelines) adherence, sufficient comments and tests, and general quality. A review may be left through GitHub or your PR may have commits added to it. Feel free to read the diffs of those commits to understand what was changed so you can learn from that feedback. Direct commits are often faster than leaving dozens of comments. These can range from nitpicks to larger improvements. Our process is to collaborate on PRs as a team to write the best code possible, meaning your PR won't always be exclusively written by you.

-When changes are requested, the maintainer will usually mark the PR as a draft again while awaiting your updates. It is your responsibility to mark it as ready for review again once you've addressed the feedback.
+When changes are requested, the maintainer will usually mark the PR as a draft again while awaiting your updates. **It is your responsibility to mark it as ready for review** again once you have addressed the feedback.

 - If a PR is a draft, the ball is in your court to move it forward.
- If it's marked as ready for review, it means there is nothing more for you to do until the maintainer has time to review it.
+- If it's marked as ready for review, it means there is nothing more for you to do until the maintainer has time to review it. (You're encouraged to work on other PRs while waiting.)

 After any number of back-and-forth cycles, a maintainer (usually Keavon who often gives the final say) will merge your PR. All your commits will be squashed into a single new commit on the `master` branch. This keeps the Git history linear and easy to follow.

-Congratulations on landing your successful contribution! Ping `@Keavon` on Discord to be given the "Code Contributor" role.
+Congratulations on landing your successful contribution! Post a request in `#📄development` on Discord to be assigned the *"Code Contributor"* role.