Skip to content

Commit

Permalink
chore(turbo): simplify contributing (vercel#8931)
Browse files Browse the repository at this point in the history
### Description

Simplify contributing

### Testing Instructions

<!--
  Give a quick description of steps to test your changes.
-->
  • Loading branch information
tknickman authored Aug 2, 2024
1 parent 3ee9ab0 commit fc115f3
Showing 1 changed file with 1 addition and 124 deletions.
125 changes: 1 addition & 124 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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

Expand Down Expand Up @@ -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][].
Expand Down

0 comments on commit fc115f3

Please sign in to comment.