Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore(turbo): simplify contributing #8931

Merged
merged 1 commit into from
Aug 2, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
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
Loading