diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 31df18c33743f..bf5d662a49aa3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,8 +2,6 @@ Thanks for your interest in contributing to Turbo! -**Important note**: At the moment, Turbo is made up of two tools, Turborepo and Turbopack, built with different languages and toolchains. In the future, Turbo will become a single toolchain built on Rust and the Turbo engine. In the meantime, please follow the respective guide when contributing to each tool: - - [Contributing to Turbo](#contributing-to-turbo) - [General Dependencies](#general-dependencies) - [Linux Dependencies](#linux-dependencies) @@ -18,17 +16,12 @@ Thanks for your interest in contributing to Turbo! - [Manually testing `turbo`](#manually-testing-turbo) - [Publishing `turbo` to the npm registry](#publishing-turbo-to-the-npm-registry) - [Creating a new release blog post](#creating-a-new-release-blog-post) - - [Adding A New Crate](#adding-a-new-crate) - - [Contributing to Turbopack](#contributing-to-turbopack) - - [Turbopack Architecture](#turbopack-architecture) - - [Testing Turbopack](#testing-turbopack) - - [Profiling Turbopack](#profiling-turbopack) - [Troubleshooting](#troubleshooting) ## General Dependencies - [Rust](https://www.rust-lang.org/tools/install) -- [cargo-groups](https://github.com/nicholaslyang/cargo-groups) (used to group crates into Turborepo-specific ones and Turbopack-specific ones) +- [cargo-groups](https://github.com/nicholaslyang/cargo-groups) ### Linux Dependencies @@ -187,122 +180,6 @@ turbo generate run "blog - "blog - update release post stats" and choose the blog post you would like to update. -## Adding A New Crate - -When adding a new crate to the repo, it is essential that it is included/excluded from the -relevant workflows. This ensures that changes to the crate are tested by the correct workflows, -but that they do not trigger unnecessary workflows as well. - -First, determine whether the crate is for Turbopack or Turborepo. If it is for Turbopack, then the crate -should be added to the `default-members` key in the root `Cargo.toml`. If the crate is for Turborepo, the -crate must be added to the `PATTERNS` list in "Turborepo related changes" section of the `test.yml` -workflow file. It must also be excluded from the "Turbopack related changes" section of the -`test.yml` workflow file. - -For instance, if we were adding a `turborepo-foo` crate, we would add the following patterns: - -```diff - - name: Turbopack related changes - id: turbopack - uses: technote-space/get-diff-action@v6 - with: - PATTERNS: | - pnpm-lock.yaml - package.json - crates/** - xtask/** - .cargo/** - rust-toolchain - !crates/turborepo/** - !crates/turborepo-lib/** - !crates/turborepo-ffi/** - !crates/turbo-updater/** -+ !crates/turborepo-foo/** - !**.md - !**.mdx - - - name: Turborepo related changes - id: turborepo - uses: technote-space/get-diff-action@v6 - with: - PATTERNS: | - pnpm-lock.yaml - package.json - crates/turborepo/** - crates/turborepo-lib/** - crates/turborepo-ffi/** - crates/turbo-updater/** -+ crates/turborepo-foo/** - .cargo/** - rust-toolchain - !**.md - !**.mdx -``` - -The crate must also be explicitly excluded from build commands -for Turbopack and included in build commands for Turborepo. -To do so, add a `--exclude turborepo-foo` flag to the Turbopack commands in -`.cargo/config.toml` such as `tp-test`, and add an `-p turborepo-foo` to the Turborepo -commands such as `tr-test`. - -Finally, the crate must be added to the Turborepo section of CODEOWNERS: - -```diff -# overrides for crates that are owned by turbo-oss - /crates/turborepo @vercel/turbo-oss - /crates/turborepo-ffi @vercel/turbo-oss -+ /crates/turborepo-foo @vercel/turbo-oss - /crates/turborepo-lib @vercel/turbo-oss - /crates/turborepo-scm @vercel/turbo-oss - /crates/turbo-updater @vercel/turbo-oss -``` - -## Contributing to Turbopack - -Turbopack uses [Cargo workspaces][workspaces] in the Turbo monorepo. You'll find -several workspaces inside the `crates/` directory. In order to run a particular -crate, you can use the `cargo run -p [CRATE_NAME]` command. - -### Turbopack Architecture - -A high-level introduction to Turbopack's architecture, workspace crates, and Turbo engine (the turbo-tasks crates) is available at [crates/turbopack/architecture.md](crates/turbopack/architecture.md). - -### Testing Turbopack - -Install `cargo-nextest` (https://nexte.st/): - -`cargo install cargo-nextest` - -Then, install dependencies for testcases: - -`pnpm install -r --side-effects-cache -C crates/turbopack/tests/node-file-trace` - -Run via: - -```shell -cargo nextest run -``` - -For the test cases you need to run `pnpm install` to install some node_modules. See [Troubleshooting][] for solutions to common problems. - -You can also create a little demo app and run - -```shell -cargo run -p node-file-trace -- print demo/index.js -``` - -Updating snapshot tests: - -In case of changes that involve updating snapshots you can use the `UPDATE=1` environment variable. - -``` -UPDATE=1 cargo nextest run -``` - -### Profiling Turbopack - -See [the profiling docs for Turbopack](https://turbo.build/pack/docs/advanced/profiling) for details. - ## Troubleshooting See [Troubleshooting][].