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.

Code quality and readability are first-class priorities in the Graphite project. Clean, well-documented code makes the codebase accessible to new contributors and sustainable over the long term. These guidelines reflect the conventions the team has established — following them closely will make code review go smoothly and your contributions land faster.

​
Linting

Clippy is the Rust linter of choice for Graphite. It should be enabled automatically in VS Code via the suggested extensions. Run it manually at any time from the project root: 
cargo clippy
Do not commit code that introduces new Clippy warnings. PRs with lint warnings will need to resolve them before merging, so catching them locally first saves a round-trip through CI.

​
Naming

Use descriptive names for variables, functions, and symbols. Minimize abbreviations — prefer spelling out full words in most cases. Monitors are wide enough to display long identifiers, and descriptive names dramatically reduce the mental burden on readers.
✅ Prefer❌ Avoid
generate_document_formatgen_doc_fmt
maximum_layer_countmax_lyr_cnt
evaluate_expressioneval_expr
Acceptable shortened forms include common, unambiguous abbreviations such as:
  • max for “maximum”
  • eval for “evaluate”
  • info for “information”
The project uses American English spelling conventions throughout. It is strongly recommended to install a spellcheck extension such as Code Spell Checker for VS Code to catch spelling mistakes before code review does.

​
Whole-Number Floats

Always write whole-number float literals as 42. rather than 42.0. This maintains consistency and brevity across the codebase. 
let x = 42.;  // correct
let x = 42.0; // avoid
For range syntax, both of the following forms are acceptable: 
0.0..42.
(0.)..42.

​
Comments

Comments are important — but they must follow consistent formatting conventions:
  • Use // for inline comments; use /// for doc comments on public items
  • Always leave one space after // or ///
  • Write // comments in Sentence case (capital first letter)
  • Do not end a single-sentence // comment with a period — unless the comment contains multiple sentences
  • Doc comments (///) should always end with a period
  • Avoid /* */ block comment style
  • Place comments on a separate line above the code they describe, not at the end of the same line
  • Do not include commented-out code in PRs open for review unless there is a compelling documented reason
// This calculates the final transform for the selected layer
let transform = compute_layer_transform(layer_id);

/// Computes the final world-space transform for a given layer.
pub fn compute_layer_transform(layer_id: LayerId) -> Transform { ... }

​
Blank Lines

Blank lines are the paragraphs of source code. Use them to group related lines into logical blocks, just as a writer uses paragraphs to organize prose.
  • Separate distinct logical steps with a blank line between them
  • Aim for at least 10% blank lines in any given block of code
  • A long, unbroken wall of logic with no blank lines is a readability concern — find sensible partitions and insert spacing between them
// Fetch the node inputs
let input_a = graph.get_input(node_id, 0);
let input_b = graph.get_input(node_id, 1);

// Compute the blended result
let result = blend(input_a, input_b, blend_mode);

// Write back to the cache
cache.insert(node_id, result);

​
Import Organization

Imports in Graphite follow a specific formatting rule that rustfmt does not enforce automatically — it must be applied by hand. Always combine imports that share a common path, but only at the same depth: 
// Before:
use crate::A::B::C;
use crate::A::B::C::Foo;
use crate::A::B::C::Bar;

// After (combined at the same depth):
use crate::A::B::C::{self, Foo, Bar};
Never combine imports at mixed path depths — do not put :: inside {}: 
// Wrong — mixed depths inside braces:
use crate::A::{B::C::Foo, X::Hello};

// Correct — separate lines for different path depths:
use crate::A::B::C::Foo;
use crate::A::X::Hello;
This rule keeps the import block clean and predictable, and makes it easy to scan which modules are being pulled in at a glance.

​
AI Contribution Policy

Many open source projects — including Graphite — have experienced a rise in low-quality PRs written partly or wholly by AI tools. These waste maintainer time and delay review of genuine contributions. The project has established firm rules to address this.
AI-generated “vibe-coded” or agent-written PRs are strictly forbidden. Submitting such a PR may be treated as a malicious spam attack against the project and can result in a permanent ban. PR descriptions and replies to reviewers must also be written by you — not generated by AI.

​
Acceptable AI usage

  • Debugging assistance and tab-completion from non-agent tools (e.g., GitHub Copilot inline completions) may assist you — including single lines of code you would have otherwise written yourself — without disclosure.
  • AI chat tools (not agents) may help generate small snippets under 40 lines, provided you manually copy, paste, and carefully review every line for correctness and consistency with your own intent. This requires disclosure in your PR.

​
Unacceptable AI usage

  • Agent-driven or “vibe-coded” PRs where the contributor does not understand the code they are submitting
  • AI-written PR descriptions, review responses, or issue comments
  • Submitting any AI-generated content without disclosure

​
Required disclosure

Graphite has zero tolerance for undisclosed AI-generated content. If your PR contains any lines you did not personally write using your own understanding:
  1. Leave a self-review comment on the specific lines in the GitHub PR diff immediately after pushing
  2. Write a detailed, human-authored justification explaining why each line is correct and appropriate
  3. Be prepared to explain the code in a code review discussion
The standard is simple: you are personally responsible for every line of code you submit. Do not submit code you cannot fully explain and defend.

Build docs developers (and LLMs) love

Get started for freeTalk to us