How to contribute

This section is a quick orientation for anyone making changes to Ruff or ty. Read CONTRIBUTING.md and AGENTS.md for the full canonical version; what follows is the digest a new contributor needs in their first hour.

Where to start

1. Find an issue. Astral labels good first issue and help wanted on GitHub. Avoid needs-design and needs-decision issues — these still need product scoping.
2. Don't open feature PRs cold. Discuss new lint rules, new ty checks, or new CLI features in an issue or Discord first. Astral's CONTRIBUTING.md is explicit: "Please do not open pull requests for new features without prior discussion."
3. Pick the right side — Ruff PRs target the Ruff guide, ty PRs target crates/ty/CONTRIBUTING.md. PR titles for ty must start with [ty] and carry the ty GitHub label.
4. AI policy. Any AI use in contributions must follow Astral's AI Policy.

The full loop

graph LR
    A[Pick issue] --> B[Branch + code]
    B --> C[Add tests<br/>insta or mdtest]
    C --> D[cargo nextest run<br/>+ insta accept]
    D --> E[cargo clippy<br/>+ uvx prek run -a]
    E --> F[Open PR]
    F --> G[Review<br/>+ snapshot diff]
    G --> H[Merge]

Each link is covered in detail:

• Development workflow — branch, run, validate.
• Testing — insta, mdtest, fuzz, the corpus harness.
• Debugging — common errors, log routing, panic triage.
• Patterns and conventions — Rust style, error handling, AST patterns, Salsa rules.
• Tooling — cargo dev, prek, codegen, the playground build.

Definition of done

A change is done when all of the following are true:

• New behavior has tests. Snapshots are reviewed and updated where appropriate.
• cargo nextest run passes.
• cargo clippy --workspace --all-targets --all-features -- -D warnings passes.
• uvx prek run -a passes.
• If you changed configuration options, CLI args, lint rules, or environment variable definitions, you ran cargo dev generate-all (or RUFF_UPDATE_SCHEMA=1 cargo test) so that schemas, docs, and references are in sync.
• The PR description links the issue and explains the user-visible change.

If any of these is missing, the PR will bounce in review.

Reviewer expectations

Reviewers will look for:

• Tests for every behavior change — unit tests, snapshots, or mdtest cases. The repo's stance is bluntly stated in AGENTS.md: "If you're not testing your changes, you're not done."
• Snapshot deltas read carefully — every changed snapshot has a reason.
• No panic!/unreachable!/.unwrap() in new code unless invariants force it. Encode constraints in types where possible.
• Imports at the top of the file, never local.
• Concise diagnostic messages for new ty checks; details belong in subdiagnostics so concise output stays readable.
• Salsa hygiene for ty: methods that touch .node() must be #[salsa::tracked] or incremental will silently break.

Where things live

You changed…	Also update…
A lint rule	crates/ruff_linter/src/rules/<plugin>/rules/<rule>.rs + codes.rs + tests under resources/test/fixtures/<plugin>/ + run cargo dev generate-all
A configuration option	The Settings builders in crates/ruff_workspace + run RUFF_UPDATE_SCHEMA=1 cargo test
The formatter	Snapshots under crates/ruff_python_formatter/tests/snapshots/ + the Black-compatibility tracker
ty type inference	mdtest fixtures under crates/ty_python_semantic/resources/mdtest/ + run with MDTEST_UPDATE_SNAPSHOTS=1
LSP behavior	crates/ruff_server or crates/ty_server + the corresponding tests

For shorter, more practical material, jump straight to development workflow.