
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>
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
).