Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/GraphiteEditor/Graphite/llms.txt

Use this file to discover all available pages before exploring further.

Collaboration is a key part of real-world software engineering. Graphite follows clear PR conventions to keep code review efficient, maintain a clean project history, and respect the time of maintainers and contributors alike. Familiarizing yourself with these guidelines before opening your first PR will save everyone significant time and confusion.

​
Before Opening a PR

This guide assumes you understand the fundamentals of Git: commits, branches, and working with multiple remotes. If you are new to Git, you will need to learn those topics independently before contributing. A good starting point is the Graphite intro webcast, which also recommends the Git Graph VS Code extension for visualizing your branch history. If you are using any AI tools in your development workflow, read the AI contribution policy before submitting your PR.

​
Branch Naming

Create a new branch before making your first commit. Keep branch names short but sufficiently descriptive, using kebab-case (hyphens between words).
  • ✅ fix-path-tool-selection-history
  • ✅ add-blur-node
  • ❌ feature/add-blur-node — do not use feature/, fix/, or similar prefixes
  • ❌ my-changes — too vague to be useful
Never open a PR from a branch named master. This makes code review considerably more difficult and pollutes the diff with unrelated history. If you have already been committing to master, create a correctly-named branch from your current state and open the PR from that branch instead.
After pushing your branch and opening a PR, you cannot rename the branch. If the name is not ideal, don’t close and re-open the PR — just keep these tips in mind for next time.

​
Opening a Pull Request

1

Push your branch to GitHub

git push origin your-branch-name
2

Open a PR on GitHub

Navigate to the Graphite repository on GitHub. You will see a prompt to open a PR for your recently pushed branch.
3

Mark it as a Draft

Unless your PR is immediately ready for review, open it as a Draft. Use the dropdown arrow next to “Create pull request” and select “Create draft pull request”. If you already opened a regular PR, use the “Convert to draft” option in the sidebar.Mark the PR as ready for review — and ping a maintainer — only when your code fully implements the required functionality and you have tested it thoroughly.
4

Write a descriptive title

Your PR title becomes the commit message in the project’s Git history. Use sentence case and imperative mood:
  • ✅ Fix path tool selection history
  • ✅ Add Gaussian blur node
  • ❌ fixed the path tool — past tense
  • ❌ Path tool fix — not imperative
5

Reference issues in the description

If you are working on a task from the #✅code-todo-list Discord channel, right-click the exact message, select “Copy Message Link”, and paste that link into your PR description.If you are working on a GitHub issue, include a reference in the PR description using one of GitHub’s closing keywords:
Closes #123
Fixes #123
Resolves #123
For tracking issues that should not be auto-closed, use Part of #123 instead. After the PR merges, update this to Closes #123 so the tracking issue links to the merged PR.If there is no associated issue, remove the pre-filled “Closes #” text from the description entirely.
6

Add context and screenshots

Optionally — but helpfully — write a brief summary of what you changed. Including screenshots or short video clips of visual changes makes review significantly faster.

​
PR Drafts

Always open new PRs as drafts first. The draft state signals that work is still in progress and no review is expected yet. Convert to “Ready for review” only when the implementation is complete and tested.
  • Draft PR → work is in progress; the ball is in your court
  • Ready for review → implementation is complete; awaiting maintainer feedback
When a maintainer requests changes, they will typically convert the PR back to draft. It is your responsibility to mark it as ready for review again once you have addressed their feedback.

​
Commit Message Conventions

Individual commit messages within your branch should follow the same conventions as the PR title: sentence case and imperative mood. These messages appear in the project Git history after squash-merge, so they should be concise but meaningful.
  • ✅ Fix incorrect color conversion in blend node
  • ✅ Refactor layer ordering logic
  • ❌ wip
  • ❌ fixed stuff

​
Code Review Etiquette

Before requesting review, it is your responsibility to:
  • Build and test your changes thoroughly — do not request review for code that obviously fails or breaks surrounding functionality
  • Do a self-review — read over the full diff in GitHub’s “Files changed” tab and catch your own mistakes before a maintainer has to
  • Remove debug artifacts — no leftover debugging code, commented-out lines, or unintended whitespace changes
  • Understand the feature — if you don’t understand why your change matters to a Graphite user, spend time using the editor and asking questions in Discord
You may leave comments on your own code in the “Files changed” tab to flag uncertainties or explain non-obvious decisions. This is also where you must disclose any AI-generated lines of code per the AI contribution policy.
Submitting a PR that obviously fails to implement the task or breaks existing functionality in an apparent way may be interpreted as low-effort or AI-generated spam, which can result in a ban under the AI contribution policy.

​
Passing CI

After pushing to your PR branch, CI will build and test your code automatically. PRs from forks require a maintainer to approve the CI run first. Your goal is for the “Editor: Dev & CI / build (pull_request)” check to show a ✅. If it fails, investigate the logs — ask a maintainer to share them if you don’t have access. Before pushing, run these locally to catch failures early: 
cargo fmt
cargo clippy
cargo test --all-features

​
Keeping Your Branch Up to Date

Always start your work from the latest master commit. As master advances, your branch will need to be synced before it can be merged. When there are no conflicts, use GitHub’s “Update branch” button (or prefer “Update with rebase” from the dropdown) to keep the history linear. 
# Enable three-way diff for easier conflict resolution
git config --global merge.conflictstyle diff3
Do not rebase or merge master into your branch every day while waiting for review — it is unnecessary and can interfere with the reviewer’s workflow. Only sync when there are conflicts that must be resolved.

​
After Merging

Once your PR is merged:
  1. Comment on the referenced issue — leave any comment (e.g., “I opened PR #456”) so the maintainers can assign the issue to you. GitHub only allows assignments to users who have commented on an issue, and assignments are made at merge time to keep closed issues cleanly organized.
  2. Update tracking issue links — change any Part of #123 references in your PR description to Closes #123.
  3. Claim your role — post in #📄development on Discord to be assigned the “Code Contributor” role after your first merged PR.

Build docs developers (and LLMs) love

Get started for freeTalk to us