[ty] contribution guide

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,8 +1,9 @@
 <!--
-Thank you for contributing to Ruff! To help us out with reviewing, please consider the following:
+Thank you for contributing to Ruff/ty! To help us out with reviewing, please consider the following:
 
 - Does this pull request include a summary of the change? (See below.)
-- Does this pull request include a descriptive title?
+- Does this pull request include a descriptive title? (Please prefix with `[ty]` for ty pull
+  requests.)
 - Does this pull request include references to any relevant issues?
 -->
 

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.

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

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.