Update Contributing and troubleshooting with comments. Also add comme…

…nt to

`setup_integration_test.sh`

CONTRIBUTING.md

@@ -22,6 +22,10 @@ Thanks for your interest in contributing to Turbo!
 
 - [Rust](https://www.rust-lang.org/tools/install)
 - [cargo-groups](https://github.com/nicholaslyang/cargo-groups)
+- NodeJS v18
+- npm v10.5.0 (note: this is determined by the GitHub Actions CI, when in doubt, look at what the runner is using)
+- capnproto
+- protoc
 
 ### Linux Dependencies
 
@@ -48,7 +52,8 @@ Turborepo uses `reqwest`, a Rust HTTP client, to make requests to the Turbo API.
 implementations: `rustls` and `native-tls`. `rustls` is a pure Rust implementation of TLS, while `native-tls`
 is a wrapper around OpenSSL. Turborepo allows users to select which implementation they want with the `native-tls`
 and `rustls-tls` features. By default, the `rustls-tls` feature is selected---this is done so that `cargo build` works
-out of the box. If you wish to select `native-tls`, you may do so by passing `--no-default-features --features native-tls`
+out of the box. If you wish to select `native-tls`, you may do so by passing
+`--no-default-features --features native-tls`
 to the build command.
 
 ### Running Turborepo Tests
@@ -71,10 +76,6 @@ Then from the root directory, you can run:
   ```bash
   pnpm test -- --filter=cli
   ```
-- A single Go unit test (see more [in the Go docs](https://pkg.go.dev/cmd/go#hdr-Test_packages))
-  ```bash
-  cd cli && go test ./[path/to/package/]
-  ```
 - Rust unit tests ([install `nextest` first](https://nexte.st/book/pre-built-binaries.html))
   ```bash
   cargo nextest run -p turborepo-lib --features rustls-tls
@@ -96,6 +97,19 @@ Then from the root directory, you can run:
 
   Note: this is not through turbo, so you'll have to build turbo yourself first.
 
+- Updating Integration Tests
+
+  ```
+  pnpm -- turbo run build --filter=cli
+  pnpm test:interactive -F turborepo-tests-integration
+  ```
+
+  You can pass a test name to run a single test, or a directory to run all tests in that directory.
+
+  ```
+  pnpm test:interactive -F turborepo-tests-integration -- run-summary.t
+  ```
+
 - Example tests
   ```bash
   pnpm test -- --filter=turborepo-tests-examples -- <example-name> <packagemanager>
@@ -104,15 +118,17 @@ Then from the root directory, you can run:
 ## Debugging Turborepo
 
 1. Install `go install github.com/go-delve/delve/cmd/dlv@latest`
-1. In VS Code's "Run and Debug" tab, select `Build Basic` to start debugging the initial launch of `turbo` against the `build` target of the Basic Example. This task is configured in [launch.json](./.vscode/launch.json).
+1. In VS Code's "Run and Debug" tab, select `Build Basic` to start debugging the initial launch of `turbo` against the
+   `build` target of the Basic Example. This task is configured in [launch.json](./.vscode/launch.json).
 
 ## Benchmarking Turborepo
 
 Follow the instructions in the [`benchmark/README.md`](./benchmark/README.md).
 
 ## Updating `turbo`
 
-You might need to update `packages/turbo` in order to support a new platform. When you do that you will need to link the module in order to be able to continue working. As an example, with `npm link`:
+You might need to update `packages/turbo` in order to support a new platform. When you do that you will need to link the
+module in order to be able to continue working. As an example, with `npm link`:
 
 ```sh
 cd ~/repos/vercel/turbo/packages/turbo
@@ -146,8 +162,10 @@ Here's a checklist of testing strategies to cover:
 There are also multiple installation scenarios worth testing:
 
 - Global-only. `turbo` is installed as global binary, no local `turbo` in repository.
-- Local-only. `turbo` is installed as local binary, no global `turbo` in PATH. turbo` is invoked via a root package script.
-- Global + local. `turbo` is installed as global binary, and local `turbo` in repository. Global `turbo` delegates to local `turbo`
+- Local-only. `turbo` is installed as local binary, no global `turbo` in PATH. turbo` is invoked via a root package
+  script.
+- Global + local. `turbo` is installed as global binary, and local `turbo` in repository. Global `turbo` delegates to
+  local `turbo`
 
 Here are a few repositories that you can test on:
 
@@ -164,15 +182,18 @@ See [the publishing guide](./release.md#release-turborepo).
 
 ## Creating a new release blog post
 
-Creating a new release post can be done via a turborepo generator. Run the following command from anywhere within the repo:
+Creating a new release post can be done via a turborepo generator. Run the following command from anywhere within the
+repo:
 
 ```bash
 turbo generate run "blog - release post"
 ```
 
 This will walk you through creating a new blog post from start to finish.
 
-NOTE: If you would like to update the stats (github stars / npm downloads / time saved) for an existing blog post that has yet to be published (useful if time has passed since the blog post was created, and up to date stats are required before publishing) - run:
+NOTE: If you would like to update the stats (github stars / npm downloads / time saved) for an existing blog post that
+has yet to be published (useful if time has passed since the blog post was created, and up to date stats are required
+before publishing) - run:
 
 ```bash
 turbo generate run "blog - "blog - update release post stats"

troubleshooting.md

@@ -5,7 +5,9 @@ These are some common issues when starting.
 ## “cargo-nextest” cannot be opened because the developer cannot be verified.
 
 On Macs, unsigned binaries cannot be run by default. To manually approve this
-app, go to: [Apple menu > System Preferences, click Security & Privacy, under the General tab](x-apple.systempreferences:com.apple.preference.security). You'll see "“cargo-nextest” was blocked from use because it is
+app, go
+to: [Apple menu > System Preferences, click Security & Privacy, under the General tab](x-apple.systempreferences:com.apple.preference.security).
+You'll see "“cargo-nextest” was blocked from use because it is
 not from an identified developer". Click the "Allow Anyway" button, and
 `cargo-nextest` can be run on the next invocation.
 
@@ -49,3 +51,10 @@ environment variable. With this, you can set different log levels per module.
 For syntax, see the [Env Filter Syntax][1]
 
 [1][https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html]
+
+## Failing integration tests due to hash changes
+
+If a lot of integration tests are failing with changes in the hash for `package-lock.json`,
+you might be using an old version of `npm`. We try to set it in the test (`setup_package_manager.sh` and
+`setup_integration_test.sh`), but if your version is too old, it might not work.
+In which case, upgrade it to whatever the GitHub Actions runner uses.

turborepo-tests/helpers/setup_integration_test.sh

@@ -5,6 +5,8 @@ set -eo pipefail
 FIXTURE_NAME="${1-basic_monorepo}"
 
 # Default to version of npm installed with Node 18.20.2
+# If CI is failing, check that this version is the same as
+# the CI runner's version of npm
 PACKAGE_MANAGER="[email protected]"
 if [[ $2 != "" ]]; then
   PACKAGE_MANAGER="$2"