From 9111c5ea9af0cecb3c4524353ebfdee065173881 Mon Sep 17 00:00:00 2001 From: Alex Eagle Date: Tue, 13 Aug 2024 13:23:49 -0700 Subject: [PATCH] chore: docs updates for 2.0 - Add a migration guide, adapted from #1671 - Add eslint in a few spots so it's more likely users discover it - Promote Aspect Workflows for CI/CD --- README.md | 25 +++++------ docs/README.md | 16 ++++--- docs/migrate_2.md | 111 ++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 134 insertions(+), 18 deletions(-) create mode 100644 docs/migrate_2.md diff --git a/README.md b/README.md index 4ff20f8e7..8823505c6 100644 --- a/README.md +++ b/README.md @@ -1,23 +1,23 @@ # Bazel rules for JavaScript -This ruleset is a high-performance and npm-compatible Bazel integration for JavaScript. +This ruleset is a high-performance Bazel integration for JavaScript, based on the [pnpm package manager](https://pnpm.io). - Lazy: only fetches/installs npm packages needed for the requested build/test targets. - Correct: works seamlessly with node.js module resolution. For example there are no pathMapping issues with TypeScript `rootDirs`. - Fast: Bazel's sandbox only sees npm packages as directories, not individual files. + shows benchmarks for fetching, installing, and linking packages under rules_js as well as typical alternatives like npm and yarn. - Supports npm "workspaces": nested npm packages in a monorepo. Many companies are successfully building with rules_js. If you're getting value from the project, please let us know! Just comment on our [Adoption Discussion](https://github.com/aspect-build/rules_js/discussions/1000). - shows benchmarks for fetching, installing, and linking packages under rules_js as well as typical alternatives like npm and yarn. - -Google does not fund development of rules_js. If your company benefits, please consider donating to continue development and maintenance work: - -rules_js is just a part of what Aspect provides: +rules_js is just a part Aspect's monorepo developer platform: +- [Aspect Workflows](https://docs.aspect.build/workflows) delivers on Bazel's promises of speed and cost-savings. + It provides Continuous Integration and Delivery, including Remote Cache and Remote Build Execution (RBE). + Best of all, it includes all the expertise that you expect from the team at Aspect! - _Need help?_ - - Community support is available on the #javascript channel on [Bazel Slack](https://slack.bazel.build/) - - This ruleset has commercial support provided by https://aspect.build/services. + - Best-effort community support is available on the #javascript channel on [Bazel Slack](https://slack.bazel.build/) + - Commercial support as a Slack Connect channel is offered by https://aspect.build/services. - See our other Bazel rules, especially those built for rules_js: - [rules_ts](https://github.com/aspect-build/rules_ts) - Bazel rules for [TypeScript](http://typescriptlang.org) - [rules_swc](https://github.com/aspect-build/rules_swc) - Bazel rules for [swc](https://swc.rs) @@ -28,6 +28,7 @@ rules_js is just a part of what Aspect provides: - [rules_jasmine](https://github.com/aspect-build/rules_jasmine) - Bazel rules to run tests using [Jasmine](https://jasmine.github.io/) - [rules_terser](https://github.com/aspect-build/rules_terser) - Bazel rules for [Terser](https://terser.org) - a JavaScript minifier - [rules_cypress](https://github.com/aspect-build/rules_cypress) - Bazel rules to run tests using [Cypress](https://cypress.io) + - [rules_lint](https://github.com/aspect-build/rules_lint) includes [eslint support](https://github.com/aspect-build/rules_lint/blob/main/docs/eslint.md). ## Bazel compatibility @@ -35,7 +36,6 @@ The ruleset is known to work with: - Bazel 7 using WORKSPACE and Bzlmod _(tested on CI)_ - Bazel 6 using WORKSPACE and Bzlmod _(tested on CI)_ -- Bazel 5 using WORKSPACE _(no longer tested on CI)_ > [!NOTE] > Remote Execution (RBE) requires at least Bazel [6.0](https://blog.bazel.build/2022/12/19/bazel-6.0.html). @@ -46,13 +46,12 @@ The ruleset is known to work with: ## Installation -From the release you wish to use: - -copy the WORKSPACE snippet into your `WORKSPACE` file. +Follow instructions from the release you wish to use: +. To use a commit rather than a release, you can point at any SHA of the repo. -For example to use commit `abc123`: +For example, to use commit `abc123` with `WORKSPACE`: 1. Replace `url = "https://github.com/aspect-build/rules_js/releases/download/v0.1.0/rules_js-v0.1.0.tar.gz"` with a GitHub-provided source archive like diff --git a/docs/README.md b/docs/README.md index 81099a0ea..c22bc0ba0 100644 --- a/docs/README.md +++ b/docs/README.md @@ -7,13 +7,12 @@ Stuck? - See the [Frequently asked questions](./faq.md) - Ask in `#javascript` on - Check for [known issues](https://github.com/aspect-build/rules_js/issues) -- Pay for support, provided by . +- Sign up for commercial support, provided as a Slack Connect channel by . ## Installation -From the release you wish to use: - -copy the WORKSPACE snippet into your `WORKSPACE` file. +Follow instructions in the release you wish to use: +. ## Usage @@ -38,7 +37,7 @@ Other recommendations: ### Node.js -rules_js depends on rules_nodejs version 5.0 or greater. +rules_js depends on rules_nodejs version 6.1.0 or greater. Installation is included in the `WORKSPACE` snippet you pasted from the Installation instructions above. @@ -305,6 +304,7 @@ Aspect has written a number of these based on rules_js, such as: - [rules_terser](https://github.com/aspect-build/rules_terser) - Bazel rules for - a JavaScript minifier - [rules_rollup](https://github.com/aspect-build/rules_rollup) - Bazel rules for - a JavaScript bundler - [rules_deno](https://github.com/aspect-build/rules_deno) - Bazel rules for Deno http://deno.land +- [rules_lint](https://github.com/aspect-build/rules_lint) includes [eslint support](https://github.com/aspect-build/rules_lint/blob/main/docs/eslint.md). You can also write your own custom rule, though this is an advanced topic and not covered in this documentation. @@ -364,6 +364,12 @@ Or, you can use it locally within a monorepo using [pnpm workspaces]. [gazelle]: https://github.com/bazelbuild/bazel-gazelle [stardoc]: https://github.com/bazelbuild/stardoc +### CI/CD setup + +We recommend using [Aspect Workflows](https://docs.aspect.build/workflows) which provides a pool of warm Bazel CI runners +for your existing CI system. This provides the promised Bazel speed and cost savings, with very little work required from your +developer infrastructure team! + ### Debugging Add [Debug options](https://docs.aspect.build/guides/bazelrc#debug-options) and [Options for JavaScript](https://docs.aspect.build/guides/bazelrc#options-for-javascript) to your project’s .bazelrc file to add the `--config=debug` settings for debugging Node.js programs. diff --git a/docs/migrate_2.md b/docs/migrate_2.md new file mode 100644 index 000000000..807ae3199 --- /dev/null +++ b/docs/migrate_2.md @@ -0,0 +1,111 @@ +# Migrating from rules_js 1.x to rules_js 2.0 + +The 2.0 release is our first major release, where we've made breaking changes to keep the codebase healthy and adaptable to users needs. We expect to make major releases no more frequently than yearly. + +Users of rules_js 1.x should expect a fairly small effort required to migrate. + +You can follow the link to each rules_js pull request in the notes below. +In many cases, updates to the testing folders (`e2e` or `examples`) are illustrative of the changes required. + +## Dependency versions + +Bazel 5 is no longer supported. Users must upgrade to Bazel 6 or greater. (#1589), (#1610) + +Minimum dependency versions have been increased: + +- `rules_nodejs` 6.1.0 (#1579) +- `aspect_bazel_lib` 2.7.1 (#1580) + +## User facing changes + +Any rules_js user is likely to encounter these changes which require some edits to your code. + +### npm_translate_lock + +The label used to link a package, [`npm_package_target_name`](https://docs.aspect.build/rulesets/aspect_rules_js/docs/npm_translate_lock/#npm_package_target_name) has changed to `pkg` (#1684). You should change your `npm_package` rules to have `name = 'pkg'`, see [examples](https://github.com/aspect-build/rules_js/pull/1684/files#diff-d13f73189fcb63af69a6bfa0eb9cb61e71d6466d2eac4c1051674b73976a1cfe). + +The `update_pnpm_lock` default value is now `False` rather than based on presence of `npm_package_lock` or `yarn_lock`. (#1624) + +Deprecated attributes have been removed from the repository rule: +- `warn_on_unqualified_tarball_url` (#1568) +- `package_json` (#1569) +- `update_pnpm_lock_node_toolchain_prefix` (#1574) +- `use_starlark_yaml_parser` (#1658) + +And one attribute from the module extension used in `MODULE.bazel`: +- `pnpm_version` (#1576) + +### npm_package + +The `npm_package#include_runfiles` attribute allows a package to ship with the default runfiles produced by the `srcs`. +The default is now `False` (#1567). + +You may need to set it back to `True` in a few cases: + +- to work-around issues with rules that don't provide everything needed in the `JsInfo` fields (`sources`, `transitive_sources`, `types` & `transitive_types`) +- to depend on the runfiles targets that don't use `JsInfo` + +### npm_import + +Two deprecated attributes were removed: +- `run_lifecycle_hooks` (#1572) +- `lifecycle_hooks_no_sandbox` (#1573) + +### js_filegroup + +`js_filegroup` has been renamed to `js_info_files` (#1615) + +It also has two new attributes, `include_sources` and `include_transitive_declarations`. These are used by helpers `gather_files_from_js_providers` + `gather_runfiles` (#1585) + +### declarations => types + +The term `declarations` has been renamed to `types` in `JsInfo` & throughout rules_js (#1619) + +### WORKSPACE + +The `nodejs_register_toolchains()` helper has been replaced by a new `rules_js_register_toolchains` WORKSPACE function (#1593). +See [examples](https://github.com/aspect-build/rules_js/pull/1593/files#diff-c808f5893f0766a46d39f5b1ff8b3cbeb5eb3cadef752af39a56ab65f1c92c93) + +The deprecated `//npm:npm_import.bzl` helper has been removed. (#1570) + +### Other + +The `expand_template` rule is removed, we recommend the [alternative in bazel-lib](https://docs.aspect.build/rulesets/aspect_bazel_lib/docs/expand_template/) (#1587) + +`js_binary`, `js_test` and `js_run_binary` have new attributes `include_sources` and `include_transitive_types`. (https://github.com/aspect-build/rules_js/commit/9b1d03c23519e6d47c59687be7f8e2327e85a931) + +## Internal changes + +These changes aren't visible to end-users. +However if you have written your own custom rules based on rules_js, changes may be required in those rules. + +### js_binary + +- refactor: make internal `unresolved_symlinks_enabled` attribute of `js_binary` mandatory (#1571) + +### NpmPackageInfo + +- refactor: rename `directory` attribute of `NpmPackageInfo` to `src` (#1575) + +### NpmPackageStoreInfo + +- refactor: don't gather files from `NpmPackageStoreInfo` providers in `gather_files_from_js_info` (#1663) +- refactor: remove unused `src_directory` from `NpmPackageStoreInfo` (#1566) + +### JsInfo + +- refactor: rename `JsInfo` `npm_package_store_deps` to `npm_package_store_infos` (#1620) +- refactor: rename `include_npm_linked_packages` to `include_npm_sources` && JsInfo `npm_linked_packages` to `npm_sources` (#1623) +- refactor: rename `declarations` to `types` in JsInfo & throughout rules_js (#1619) +- refactor: re-order fields in `JsInfo` for readability (#1648) + +### Other + +- refactor: rename `gather_files_from_js_providers` to `gather_files_from_js_info` (#1617) +- refactor: rename `gather_files_from_js_info` to `gather_files_from_js_infos` (#1665) +- refactor: remove `utils.home_directory` and use `get_home_directory` from Aspect bazel-lib utils instead (#1606) +- refactor: remove `//js:enable_runfiles` and use `@aspect_bazel_lib//lib:enable_runfiles` instead (#1605) +- fix: drop `.sh` extension from `js_binary`, `merger` and `js_image_layer` launchers (#1586) +- refactor: remove unused `NpmLinkedPackageInfo` provider and corresponding unused `npm_linked_packages` from JsInfo; rename load bearing `npm_linked_package_files` to `npm_linked_packages` (#1588) +- refactor: remove deprecated `//js/private:enable_runfiles` and `//js/private:experimental_allow_unresolved_symlinks` (#1577) +- refactor: remove `JS_LIBRARY_DATA_ATTR` and `DOWNSTREAM_LINKED_NPM_DEPS_DOCSTRING` from js_helpers