From 00f672a83b8435aa7e981eb6a8b4c42774ef2fbb Mon Sep 17 00:00:00 2001 From: Carl Meyer Date: Tue, 13 May 2025 01:55:01 -0700 Subject: [PATCH] [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 Co-authored-by: David Peter --- .github/PULL_REQUEST_TEMPLATE.md | 5 +- CONTRIBUTING.md | 5 ++ crates/ty/CONTRIBUTING.md | 141 +++++++++++++++++++++++++++++++ crates/ty/README.md | 24 +----- 4 files changed, 153 insertions(+), 22 deletions(-) create mode 100644 crates/ty/CONTRIBUTING.md diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 5b6455590f..3bc48f3cc6 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,8 +1,9 @@ diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9281bd1086..aab1ed1e72 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,6 +2,11 @@ Welcome! We're happy to have you here. Thank you in advance for your contribution to Ruff. +> [!NOTE] +> +> This guide is for Ruff. If you're looking to contribute to ty, please see [the ty contributing +> guide](https://github.com/astral-sh/ruff/blob/main/crates/ty/CONTRIBUTING.md). + ## The Basics Ruff welcomes contributions in the form of pull requests. diff --git a/crates/ty/CONTRIBUTING.md b/crates/ty/CONTRIBUTING.md new file mode 100644 index 0000000000..de7bedb705 --- /dev/null +++ b/crates/ty/CONTRIBUTING.md @@ -0,0 +1,141 @@ +# 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 need [uv](https://docs.astral.sh/uv/getting-started/installation/) (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: + +```shell +uv tool install pre-commit +pre-commit 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 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](https://marketplace.visualstudio.com/items?itemName=rust-lang.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`](./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/). + +## 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 (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`](./docs/mypy_primer.md) +for instructions on running these checks 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 diff --git a/crates/ty/README.md b/crates/ty/README.md index e0b644c3ea..fb98292a0f 100644 --- a/crates/ty/README.md +++ b/crates/ty/README.md @@ -1,25 +1,9 @@ # ty ty is an extremely fast type checker. -Currently, it is a work-in-progress and not ready for user testing. +Currently, it is a work-in-progress and not ready for production use. -ty is designed to prioritize good type inference, even in unannotated code, -and aims to avoid false positives. +The Rust code for ty lives in this repository; see [CONTRIBUTING.md](CONTRIBUTING.md) for more +information on contributing to ty. -While ty will produce similar results to mypy and pyright on many codebases, -100% compatibility with these tools is a non-goal. -On some codebases, ty's design decisions lead to different outcomes -than you would get from running one of these more established tools. - -## Contributing - -Core type checking tests are written as Markdown code blocks. -They can be found in [`ty_python_semantic/resources/mdtest`][resources-mdtest]. -See [`ty_test/README.md`][mdtest-readme] for more information -on the test framework itself. - -The list of open issues can be found [here][open-issues]. - -[mdtest-readme]: ../ty_test/README.md -[open-issues]: https://github.com/astral-sh/ty/issues -[resources-mdtest]: ../ty_python_semantic/resources/mdtest +See [the ty repo](https://github.com/astral-sh/ty) for ty documentation and releases.