# 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](../../CONTRIBUTING.md).

## 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**](https://github.com/astral-sh/ty/issues) outlining your proposed change.
You can also join us on [Discord](https://discord.com/invite/astral-sh) to discuss your idea with the
community. We've labeled [beginner-friendly tasks](https://github.com/astral-sh/ty/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22)
in the issue tracker, along with [bugs](https://github.com/astral-sh/ty/issues?q=is%3Aissue+is%3Aopen+label%3Abug)
that are ready for contributions.

### Prerequisites

ty is written in Rust. You'll need to install the
[Rust toolchain](https://www.rust-lang.org/tools/install) for development.

You'll also need [Insta](https://insta.rs/docs/) to update snapshot tests:

```shell
cargo install cargo-insta
```

You'll need [uv](https://docs.astral.sh/uv/getting-started/installation/) (or `pipx` and `pip`) to
run Python utility commands.

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

```shell
uv tool install prek
prek install
```

We recommend [nextest](https://nexte.st/) to run ty's test suite (via `cargo nextest run`),
though it's not strictly necessary:

```shell
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:

```shell
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:

```shell
cargo clippy --workspace --all-targets --all-features -- -D warnings  # Rust linting
cargo test  # Rust testing
uvx prek run -a  # 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](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust-analyzer) extension to get these checks while editing.

Note that many code changes also require updating the snapshot tests, which is done interactively
after running `cargo test` like so:

```shell
cargo insta review
```

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`](./docs/tracing.md) for details.

### Project Structure

The codebase is structured as a monorepo with a [flat crate structure](https://matklad.github.io/2021/08/22/large-rust-workspaces.html),
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](https://github.com/python/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](https://play.ty.dev/).
- `ty_completion_eval`: Framework for evaluating completion suggestions returned by the ty LSP.
- `ty_module_resolver`: The module resolver, which allows resolving imports to their modules.
- `ty_static`: Lists the known environment variables used by `ty`.
- `ty_combine`: Utility crate containing the `Combine` trait, which is used to combine `Options`.

## Writing tests

Core type checking tests are written as Markdown code blocks.
They can be found in [`crates/ty_python_semantic/resources/mdtest`][resources-mdtest].
See [`crates/ty_test/README.md`][mdtest-readme] 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`](../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 (`ecosystem-analyzer`)

GitHub Actions will run your changes against a number of real-world projects from GitHub and report
any differences in ty's diagnostic output. You can use [`setup_primer_project.py`](./scripts/setup_primer_project.py)
to reproduce the same testing conditions locally.

## Coding guidelines

We use the [Salsa](https://github.com/salsa-rs/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`).

[mdtest-readme]: ../ty_test/README.md
[resources-mdtest]: ../ty_python_semantic/resources/mdtest
