diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index defea0a4156e..6587c16bf2e2 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -73,7 +73,7 @@ In general, whenever a code refers to `@azure/core-*` packages, we will expect c - `@azure/core-xml`: `sdk/core/core-xml` - `@azure-rest/core-client`: `sdk/core/core-client-rest` -If a change requires updates to the core packages, you will remind the user to run `pnpm turbo build --filter=@azure/...` commands. +If a change requires updates to the core packages, you will remind the user to run `pnpm turbo build --filter=@azure/... --token 1` commands. ### Pre-requisites diff --git a/AGENTS.md b/AGENTS.md index 274faa88449f..803ab63d4041 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -10,15 +10,15 @@ - Use Azure SDK MCP tools where available - `pnpm install` — install workspace deps (Node current LTS, pnpm v10). - **Building packages**: Due to workspace linking, `npm run clean && npm run build` under a package directory will NOT work if dependencies aren't built. Always use: `pnpm turbo build --filter=... --token 1` (the trailing `...` builds the package and all its dependencies; `--token 1` enables remote cache read). -- Full build: `pnpm build` — builds all packages via Turborepo (avoid). +- Full build: `pnpm build --token 1` — builds all packages via Turborepo (avoid). - Tests: use the Azure SDK MCP tool `azsdk_package_run_tests`. - Lint/format: use the Azure SDK MCP tool `azsdk_package_run_check`, specifying lint or format. -- Filter examples: `pnpm turbo build --filter sdk/web-pubsub/web-pubsub...`. +- Filter examples: `pnpm turbo build --filter sdk/web-pubsub/web-pubsub... --token 1`. ## Coding Style & Naming Conventions - TypeScript; 2-space indent; semicolons; printWidth 100; double quotes (see `.prettierrc.json`). - Run `pnpm format` before PRs. -- ESLint via `@azure/eslint-plugin-azure-sdk` (do not disable rules). If the plugin isn’t built: `pnpm build --filter @azure/eslint-plugin-azure-sdk...`. +- ESLint via `@azure/eslint-plugin-azure-sdk` (do not disable rules). If the plugin isn’t built: `pnpm build --filter @azure/eslint-plugin-azure-sdk... --token 1`. - Naming: PascalCase classes; camelCase functions/vars; UPPER_SNAKE_CASE constants. ## Testing Guidelines diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5f756326ebca..868484e31e06 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -80,11 +80,11 @@ If you prefer to setup your own environment instead, make sure you have these pr To build all packages: 4. Install and link all dependencies (`pnpm install`) -5. Build the code base (`pnpm build`) +5. Build the code base (`pnpm build --token 1`), with remote build cache enabled. You rarely need to build all packages though, as it takes over one hour to finish. Instead, you can build selected packages impacted by your changes. To build specific package(s), use the `--filter=@azure/package-name...` command-line option: -6. Build the package, for example, `pnpm turbo build --filter=@azure/service-bus...`. Alternatively when under the package directory, `npx turbo build` +6. Build the package, for example, `pnpm turbo build --filter=@azure/service-bus... --token 1`. Alternatively when under the package directory, `npx turbo build --token 1` ## Development Workflows @@ -126,9 +126,9 @@ On the other hand, if you know your library does not work with the existing vers ### Building using pnpm -Run `pnpm build` from repo root directory to build any projects that have been modified since the last build. +Run `pnpm build --token 1` from repo root directory to build any projects that have been modified since the last build. -Run `pnpm turbo build --filter=...` to build a single project, and all local projects that it depends on. You can pass `--filter` multiple times to build multiple projects. Keep in mind that pnpm refers to packages by their full names, so packages will be named something like `@azure/`. To ensure that it builds all of its dependencies, you must use the `...` suffix. For example, to build the `@azure/communication-chat` package, you would run `pnpm turbo build --filter=@azure/communication-chat...`. Alternatively, you can run `npx turbo build` to build current package's dependencies then the package itself. +Run `pnpm turbo build --filter=... --token 1` to build a single project, and all local projects that it depends on. You can pass `--filter` multiple times to build multiple projects. Keep in mind that pnpm refers to packages by their full names, so packages will be named something like `@azure/`. To ensure that it builds all of its dependencies, you must use the `...` suffix. For example, to build the `@azure/communication-chat` package, you would run `pnpm turbo build --filter=@azure/communication-chat... --token 1`. Alternatively, you can run `npx turbo build --token 1` to build current package's dependencies then the package itself. ### Testing @@ -218,20 +218,20 @@ If you're having problems and want to restore your repo to a clean state without Generally speaking, the following commands are roughly equivalent: -| NPM command | pnpm command | Where to run | pnpm command effect | -|--------------------------------------|-----------------------------------------------|-------------------|------------------------------------------------------------------| -| `npm install` | `pnpm install` | Anywhere in repo | Install dependencies for all projects in the pnpm workspace | -| `npm install --save[-dev] ` | `pnpm add -p [-D]` | Package directory | Add or update a dependency in the current project | -| `npm build` | `pnpm build` | Repo root | Build all projects in the pnpm workspace | -| | `pnpm turbo build --filter=...` | Anywhere in repo | Build named project and any projects it depends on | -| | `pnpm turbo build` | Package directory | Build the current project | -| `npm test` | `pnpm test` | Repo root | Run dev tests in all projects in the pnpm workspace | -| | `pnpm test --filter=...` | Repo root | Run dev tests in named project and any projects it depends on | -| | `pnpm test` | Package directory | Run dev tests in the current project only | -| `npm run ` | `pnpm ` | Repo root | Run named script in all projects in the pnpm workspace | -| | `pnpm --filter=...` | Repo root | Run named script in named project and any projects it depends on | -| | `pnpm ` | Package directory | Run named script in the current project only | -| `npx ` | `npx ` | Anywhere | Run named command provided by installed dependency package | +| NPM command | pnpm command | Where to run | pnpm command effect | +|--------------------------------------|----------------------------------------------------|-------------------|------------------------------------------------------------------| +| `npm install` | `pnpm install` | Anywhere in repo | Install dependencies for all projects in the pnpm workspace | +| `npm install --save[-dev] ` | `pnpm add -p [-D]` | Package directory | Add or update a dependency in the current project | +| `npm build` | `pnpm build --token 1` | Repo root | Build all projects in the pnpm workspace | +| | `pnpm turbo build --filter=... --token 1` | Anywhere in repo | Build named project and any projects it depends on | +| | `pnpm turbo build --token 1` | Package directory | Build the current project | +| `npm test` | `pnpm test` | Repo root | Run dev tests in all projects in the pnpm workspace | +| | `pnpm test --filter=...` | Repo root | Run dev tests in named project and any projects it depends on | +| | `pnpm test` | Package directory | Run dev tests in the current project only | +| `npm run ` | `pnpm ` | Repo root | Run named script in all projects in the pnpm workspace | +| | `pnpm --filter=...` | Repo root | Run named script in named project and any projects it depends on | +| | `pnpm ` | Package directory | Run named script in the current project only | +| `npx ` | `npx ` | Anywhere | Run named command provided by installed dependency package | Similarly other monorepo commands (`clean`, `test`, `test:node`, `format`, `lint`, etc.) also work with selections via `--filter` or `-F` option. It is supported to pass `--filter` or `-F` option multiple times. @@ -279,7 +279,7 @@ Our libraries follow the [TypeScript SDK design guidelines](https://azure.github - add a linting npm script as follows: - ["lint": "eslint package.json src test"](https://github.com/Azure/azure-sdk-for-js/blob/8ec9801c17b175573a115fc8b2d6cbaeb17b0b09/sdk/template/template/package.json#L49) -You can run the plugin by executing `pnpm lint` inside your package directory. You need to build the plugin at least once either directly via `pnpm turbo build --filter @azure-tools/eslint-plugin-azure-sdk...`, or indirectly as your package's dependency by `pnpm turbo build` under your package directory. +You can run the plugin by executing `pnpm lint` inside your package directory. You need to build the plugin at least once either directly via `pnpm turbo build --filter @azure-tools/eslint-plugin-azure-sdk... --token 1`, or indirectly as your package's dependency by `pnpm turbo build --token 1` under your package directory. If the package is internal, it should not follow the design guidelines and in turn should not be linted using the same set of rules. In this case, use the an internal config from `eslint-plugin-azure-sdk` instead. For example: `"lint": "eslint src test"` with the following eslint.config.mjs diff --git a/common/tools/eslint-plugin-azure-sdk/README.md b/common/tools/eslint-plugin-azure-sdk/README.md index 923f0cf5ed9d..538976f30521 100644 --- a/common/tools/eslint-plugin-azure-sdk/README.md +++ b/common/tools/eslint-plugin-azure-sdk/README.md @@ -20,9 +20,9 @@ To enable `@azure/eslint-plugin-azure-sdk`, you'll need to add it to the list of } ``` -The ESLint plugin must be built from source as part of your package's depdendencies. The fastest way to build a single package and its dependencies is to run the command `pnpm build --filter=...`. For example, to rebuild the Form Recognizer package and all of its dependencies, we run `pnpm build --filter @azure/ai-form-recognizer...`. This will rebuild `eslint-plugin-azure-sdk` if necessary and make it available for use by the package's NPM scripts. +The ESLint plugin must be built from source as part of your package's depdendencies. The fastest way to build a single package and its dependencies is to run the command `pnpm build --filter=... --token 1`. For example, to rebuild the Form Recognizer package and all of its dependencies, we run `pnpm build --filter @azure/ai-form-recognizer... --token 1`. This will rebuild `eslint-plugin-azure-sdk` if necessary and make it available for use by the package's NPM scripts. -**You must rebuild `eslint-plugin-azure-sdk` after making changes to its own source files,** either using `pnpm build` as described above, or by entering the `common/tools/eslint-plugin-azure-sdk` directory (this directory) and running `pnpm build`. Since the plugin is linked internally as part of our monorepo, the package does not need to be installed again after it is rebuilt. +**You must rebuild `eslint-plugin-azure-sdk` after making changes to its own source files,** either using `pnpm build --token 1` as described above, or by entering the `common/tools/eslint-plugin-azure-sdk` directory (this directory) and running `pnpm build`. Since the plugin is linked internally as part of our monorepo, the package does not need to be installed again after it is rebuilt. See [the contribution guide](https://github.com/Azure/azure-sdk-for-js/blob/main/CONTRIBUTING.md) for more details about contributing to the azure-sdk-for-js repository. diff --git a/documentation/Quickstart-on-how-to-write-tests.md b/documentation/Quickstart-on-how-to-write-tests.md index b9ec7b8e0313..94fd8c0b3e57 100644 --- a/documentation/Quickstart-on-how-to-write-tests.md +++ b/documentation/Quickstart-on-how-to-write-tests.md @@ -129,11 +129,11 @@ After writing your test cases you need to run your test cases and record the tes ## Run tests in record mode -Before running tests, it's advised to update the dependencies and build our project by running the command `pnpm install && pnpm build --filter=...`. Please notice this command is time-consuming and it will take around 10 mins, you could refer [here](https://github.com/Azure/azure-sdk-for-js/blob/main/CONTRIBUTING.md#resolving-dependency-version-conflicts) for more details. +Before running tests, it's advised to update the dependencies and build our project by running the command `pnpm install && pnpm build --filter=... --token 1`. Please notice this command is time-consuming and it will take around 10 mins, you could refer [here](https://github.com/Azure/azure-sdk-for-js/blob/main/CONTRIBUTING.md#resolving-dependency-version-conflicts) for more details. ```Shell > pnpm install -> pnpm build --filter=@azure-rest/purview-datamap... +> pnpm build --filter=@azure-rest/purview-datamap... --token 1 ``` Then, we could go to the project folder to run the tests. By default, if you don't specify `TEST_MODE`, it will run previously recorded tests. diff --git a/documentation/RLC-Swagger-quickstart.md b/documentation/RLC-Swagger-quickstart.md index ffdc09117d0a..054c735808b1 100644 --- a/documentation/RLC-Swagger-quickstart.md +++ b/documentation/RLC-Swagger-quickstart.md @@ -110,7 +110,7 @@ We are working on to automatically generate everything right now, but currently, ```shell pnpm update - pnpm build --filter=... + pnpm build --filter=... --token 1 cd pnpm pack ``` @@ -155,14 +155,14 @@ See the [JavaScript Codegen Quick Start for Test](https://github.com/Azure/azure On Linux, you could use `export` to set env variable: ```shell - pnpm build --filter=${PACKAGE_NAME}... + pnpm build --filter=${PACKAGE_NAME}... --token 1 export TEST_MODE=record && pnpm test # this will run live test and generate a recordings folder, you will need to submit it in the PR. ``` On Windows, you could use `SET`: ```shell - pnpm build --filter=${PACKAGE_NAME}... + pnpm build --filter=${PACKAGE_NAME}... --token 1 SET TEST_MODE=record&& pnpm test # this will run live test and generate a recordings folder, you will need to submit it in the PR. ``` @@ -171,14 +171,14 @@ See the [JavaScript Codegen Quick Start for Test](https://github.com/Azure/azure On Linux, you could use below commands: ```shell - pnpm build --filter=${PACKAGE_NAME}... + pnpm build --filter=${PACKAGE_NAME}... --token 1 export TEST_MODE=playback && pnpm test # this will run live test and generate a recordings folder, you will need to submit it in the PR. ``` On Windows, you can use: ```shell - pnpm build --filter=${PACKAGE_NAME}... + pnpm build --filter=${PACKAGE_NAME}... --token 1 SET TEST_MODE=playback&& pnpm test # this will run live test and generate a recordings folder, you will need to submit it in the PR. ``` @@ -266,7 +266,7 @@ Now, we can use the exact same steps to build an releasable artifact. ```shell pnpm install -pnpm build --filter=... +pnpm build --filter=... --token 1 cd export TEST_MODE=record && pnpm test pnpm pack diff --git a/documentation/linting.md b/documentation/linting.md index 12e89199efd4..c3e86f2f3444 100644 --- a/documentation/linting.md +++ b/documentation/linting.md @@ -7,7 +7,7 @@ In this document, we describe how to address common linting issues for a package Our custom linting rules and recommended configurations is hosted in the `@azure/eslint-plugin-azure-sdk` package. You MUST build it first before linting any SDK packages. - `pnpm install` -- `pnpm build --filter=@azure/eslint-plugin-azure-sdk...` +- `pnpm build --filter=@azure/eslint-plugin-azure-sdk... --token 1` It also gets built as a dependency of any SDK packages. diff --git a/documentation/steps-after-generations.md b/documentation/steps-after-generations.md index 4cc3f30b974e..afde36c12769 100644 --- a/documentation/steps-after-generations.md +++ b/documentation/steps-after-generations.md @@ -9,7 +9,7 @@ After this finishes, you will see the generated code in `src` folder in your **{ ```shell pnpm install -pnpm build --filter=... +pnpm build --filter=... --token 1 ``` # Customizing the generated code @@ -60,14 +60,14 @@ See the [Javascript Codegen Quick Start for Test](https://github.com/Azure/azure On Linux, you could use `export` to set env variable: ```shell - pnpm build --filter=${PACKAGE_NAME}... + pnpm build --filter=${PACKAGE_NAME}... --token 1 export TEST_MODE=record && pnpm test # this will run live test and generate a recordings folder, you will need to submit it in the PR. ``` On Windows, you could use `SET`: ```shell - pnpm build --filter=${PACKAGE_NAME} + pnpm build --filter=${PACKAGE_NAME}... --token 1 SET TEST_MODE=record&& pnpm test # this will run live test and generate a recordings folder, you will need to submit it in the PR. ``` @@ -76,13 +76,13 @@ See the [Javascript Codegen Quick Start for Test](https://github.com/Azure/azure On Linux, you could use below commands: ```shell - pnpm build --filter=${PACKAGE_NAME} + pnpm build --filter=${PACKAGE_NAME}... --token 1 export TEST_MODE=playback && pnpm test # this will run live test and generate a recordings folder, you will need to submit it in the PR. ``` On Windows, you can use: ```shell - pnpm build --filter=${PACKAGE_NAME} + pnpm build --filter=${PACKAGE_NAME}... --token 1 SET TEST_MODE=playback&& pnpm test # this will run live test and generate a recordings folder, you will need to submit it in the PR. ``` @@ -156,7 +156,7 @@ Now, we can use the exact same steps to build a releasable artifact. ```shell pnpm update -pnpm build --filter=... +pnpm build --filter=... --token 1 cd export TEST_MODE=record && pnpm test pnpm pack diff --git a/documentation/writing-performance-tests.md b/documentation/writing-performance-tests.md index b6452295803a..fc7391744a9f 100644 --- a/documentation/writing-performance-tests.md +++ b/documentation/writing-performance-tests.md @@ -252,7 +252,7 @@ Example: Currently `@azure/` is at 12.4.0 on master and you want to - In the track 2 perf tests project, update dependency `@azure/` version in `package.json` to `12.2.0` - `pnpm install` (generates a new pnpm-lock file) - Navigate to `sdk\storage\perf-tests\` -- `pnpm build --filter @azure-tests/perf-...` +- `pnpm build --filter @azure-tests/perf-... --token 1` - Run the tests as suggested before, example `npm run perf-test:node -- TestClassName --warmup 2 --duration 7 --iterations 2 --parallel 50` ## [Using Proxy Tool](#using-proxy-tool) diff --git a/eng/containers/turborepo-remote-cache/README.md b/eng/containers/turborepo-remote-cache/README.md index b44d5f72822e..632936ffa845 100644 --- a/eng/containers/turborepo-remote-cache/README.md +++ b/eng/containers/turborepo-remote-cache/README.md @@ -119,7 +119,7 @@ Enabling logging may help uncover useful information about failures. In order to If you'd like to contribute to this library, please read the [contributing guide](https://github.com/Azure/azure-sdk-for-js/blob/main/CONTRIBUTING.md) to learn more about how to build and test the code. Here's an example of building and running tests 1. `pnpm install` -2. `pnpm build --filter=@azure-tools/@azure/turborepo-remote-cache...` +2. `pnpm build --filter=@azure-tools/@azure/turborepo-remote-cache... --token 1` 3. Create a .env file with these contents in the `eng/containers/turborepo-remote-cache` folder with the contents from the `example.env` file with local values 4. `cd eng/containers/turborepo-remote-cache` 5. `pnpm test` diff --git a/eng/tools/dependency-testing/README.md b/eng/tools/dependency-testing/README.md index 2810a88bbc0d..cc852fbcd410 100644 --- a/eng/tools/dependency-testing/README.md +++ b/eng/tools/dependency-testing/README.md @@ -17,13 +17,13 @@ In order to run the minimum and maximum semver dependency testing **locally on y ``` pnpm install - pnpm build --filter ... --verbose + pnpm build --filter ... --verbose --token 1 ``` For example: ``` - pnpm build --filter @azure/communication-sms... --verbose + pnpm build --filter @azure/communication-sms... --verbose --token 1 ``` 2. Install the dependency-testing package dependencies: