ruff/crates/ty/CONTRIBUTING.md
Carl Meyer 00f672a83b
Some checks are pending
CI / Determine changes (push) Waiting to run
CI / cargo fmt (push) Waiting to run
CI / cargo clippy (push) Blocked by required conditions
CI / cargo test (linux) (push) Blocked by required conditions
CI / cargo test (linux, release) (push) Blocked by required conditions
CI / cargo test (windows) (push) Blocked by required conditions
CI / cargo test (wasm) (push) Blocked by required conditions
CI / cargo build (release) (push) Waiting to run
CI / cargo build (msrv) (push) Blocked by required conditions
CI / cargo fuzz build (push) Blocked by required conditions
CI / fuzz parser (push) Blocked by required conditions
CI / test scripts (push) Blocked by required conditions
CI / ecosystem (push) Blocked by required conditions
CI / Fuzz for new ty panics (push) Blocked by required conditions
CI / cargo shear (push) Blocked by required conditions
CI / python package (push) Waiting to run
CI / pre-commit (push) Waiting to run
CI / mkdocs (push) Waiting to run
CI / formatter instabilities and black similarity (push) Blocked by required conditions
CI / test ruff-lsp (push) Blocked by required conditions
CI / check playground (push) Blocked by required conditions
CI / benchmarks (push) Blocked by required conditions
[ty Playground] Release / publish (push) Waiting to run
[ty] contribution guide (#18061)
First take on a contributing guide for `ty`. Lots of it is copied from
the existing Ruff contribution guide.

I've put this in Ruff repo, since I think a contributing guide belongs
where the code is. I also updated the Ruff contributing guide to link to
the `ty` one.

Once this is merged, we can also add a link from the `CONTRIBUTING.md`
in ty repo (which focuses on making contributions to things that are
actually in the ty repo), to this guide.

I also updated the pull request template to mention that it might be a
ty PR, and mention the `[ty]` PR title prefix.

Feel free to update/modify/merge this PR before I'm awake tomorrow.

---------

Co-authored-by: Dhruv Manilawala <dhruvmanila@gmail.com>
Co-authored-by: David Peter <mail@david-peter.de>
2025-05-13 10:55:01 +02:00

5.9 KiB

Contributing to ty

Welcome! We're happy to have you here. Thank you in advance for your contribution to ty.

Note

This guide is for ty. If you're looking to contribute to Ruff, please see the Ruff contributing guide.

The Basics

We welcome contributions in the form of pull requests.

For small changes (e.g., bug fixes), feel free to submit a PR.

For larger changes (e.g. new diagnostics, new functionality, new configuration options), consider creating an issue outlining your proposed change. You can also join us on Discord to discuss your idea with the community. We've labeled beginner-friendly tasks in the issue tracker, along with bugs that are ready for contributions.

Prerequisites

ty is written in Rust. You'll need to install the Rust toolchain for development.

You'll need uv (or pipx and pip) to run Python utility commands.

You can optionally install pre-commit hooks to automatically run the validation checks when making a commit:

uv tool install pre-commit
pre-commit install

We recommend nextest to run ty's test suite (via cargo nextest run), though it's not strictly necessary:

cargo install cargo-nextest --locked

Throughout this guide, any usages of cargo test can be replaced with cargo nextest run, if you choose to install nextest.

Development

After cloning the repository, run ty locally from the repository root with:

cargo run --bin ty -- check --project /path/to/project/

Prior to opening a pull request, ensure that your code has been auto-formatted, and that it passes both the lint and test validation checks:

cargo clippy --workspace --all-targets --all-features -- -D warnings  # Rust linting
cargo test  # Rust testing
uvx pre-commit run --all-files --show-diff-on-failure  # Rust and Python formatting, Markdown and Python linting, etc.

These checks will run on GitHub Actions when you open your pull request, but running them locally will save you time and expedite the merge process.

If you're using VS Code, you can also install the recommended rust-analyzer extension to get these checks while editing.

Include the text [ty] at the beginning of your pull request title, to distinguish ty pull requests from Ruff ones.

Your pull request will be reviewed by a maintainer, which may involve a few rounds of iteration prior to merging.

Debugging ty

ty can optionally emit extensive tracing output, which can be very useful in understanding its operation and debugging issues; see crates/ty/docs/tracing.md for details.

Project Structure

The codebase is structured as a monorepo with a flat crate structure, such that all crates are contained in a flat crates directory.

The vast majority of ty's code lives in the ty_python_semantic crate (located at crates/ty_python_semantic). As a contributor, that's the crate that'll probably be most relevant to you.

At the time of writing, the repository includes the following ty-specific crates (in addition to crates shared with Ruff, such as ruff_db, ruff_python_ast, and ruff_python_parser):

  • ty_python_semantic: The core type checker, which includes the type inference engine and semantic analysis.
  • ty_test: The Markdown-based test framework for ty, "mdtest".
  • ty: The command-line interface.
  • ty_ide: IDE features (hover, go-to-definition, autocomplete) for the language server.
  • ty_project: Discovery and representation of a Python project to be checked by ty.
  • ty_server: The ty language server.
  • ty_vendored: A vendored copy of typeshed, which holds type annotations for the Python standard library.
  • ty_wasm: library crate for exposing ty as a WebAssembly module. Powers the ty Playground.

Writing tests

Core type checking tests are written as Markdown code blocks. They can be found in crates/ty_python_semantic/resources/mdtest. See crates/ty_test/README.md for more information on the test framework itself.

Any ty pull request to improve ty's type inference or type checking logic should include mdtests demonstrating the effect of the change.

We write mdtests in a "literate" style, with prose explaining the motivation of each test, and any context necessary to understand the feature being demonstrated.

Property tests

ty uses property-based testing to test the core type relations. These tests are located in crates/ty_python_semantic/src/types/property_tests.rs.

The property tests do not run in CI on every PR, just once daily. It is advisable to run them locally after modifying core type relation methods (is_subtype_of, is_equivalent_to, etc.) to ensure that the changes do not break any of the properties.

Ecosystem CI (mypy-primer)

GitHub Actions will run your changes against a number of real-world projects from GitHub and report on any linter or formatter differences. See crates/ty/docs/mypy_primer.md for instructions on running these checks locally.

Coding guidelines

We use the Salsa library for incremental computation. Many methods take a Salsa database (usually db: &'db dyn Db) as an argument. This should always be the first argument (or second after self).