From 44aa27d33c3071b9d27f5041972844efa85eb816 Mon Sep 17 00:00:00 2001 From: Alex Eagle Date: Fri, 18 Dec 2020 08:18:29 -0800 Subject: [PATCH] docs: update docs for release --- DEVELOPING.md | 4 +- docs/Built-ins.html | 74 +++++++++++++- docs/Built-ins.md | 75 +++++++++++++- docs/Karma.md | 235 ++++++++++++++++++++++++++++++++++++++++++++ docs/install.html | 4 +- 5 files changed, 378 insertions(+), 14 deletions(-) create mode 100755 docs/Karma.md diff --git a/DEVELOPING.md b/DEVELOPING.md index 4ba51a1ab0..db3f7bdc0a 100644 --- a/DEVELOPING.md +++ b/DEVELOPING.md @@ -47,11 +47,11 @@ Check if there are any breaking changes since the last tag - if so, this will be 1. `npm version [major|minor|patch]` (`major` if there are breaking changes, `minor` if there are new features, otherwise `patch`) 1. Manually update the CHANGELOG.md based on the commits since the last release. Look for breaking changes that weren't documented. 1. If publishing from inside Google, set NPM_REGISTRY="--registry https://wombat-dressing-room.appspot.com" in your environment -1. Build npm packages and publish them: `./scripts/publish_release.sh` +1. Build npm packages and publish them: `./scripts/publish_release.sh` (for a release candidate, add arguments `publish next`) 1. Run `./scripts/update_nested_lock_files.sh` to update the lock files in all nested workspaces to new release 1. `git commit -a -m 'chore: update lock files for release'` 1. `git push upstream && git push upstream --tags` 1. (Manual for now): go to the [releases] page, edit the release with rough changelog (especially note any breaking changes!) and upload the release artifact from `rules_nodejs-[version].tar.gz`. Also copy the release notes from CHANGELOG.md -1. Announce the release on Angular slack in `#tools-abc-discuss` +1. Announce the release on Bazel slack in `#javascript` [releases]: https://github.com/bazelbuild/rules_nodejs/releases diff --git a/docs/Built-ins.html b/docs/Built-ins.html index 87c90eed1c..97f099a799 100755 --- a/docs/Built-ins.html +++ b/docs/Built-ins.html @@ -939,8 +939,9 @@

npm_install

USAGE

-npm_install(name, args, data, environment, included_files, manual_build_file_contents, package_json,
-            package_lock_json, quiet, repo_mapping, strict_visibility, symlink_node_modules, timeout)
+npm_install(name, args, data, environment, included_files, manual_build_file_contents, npm_command,
+            package_json, package_lock_json, quiet, repo_mapping, strict_visibility,
+            symlink_node_modules, timeout)

Runs npm install during workspace setup.

@@ -949,6 +950,24 @@

npm_install

set to another value in the environment attribute). Scripts may use to this to check if yarn is being run by the npm_install repository rule.

+

LOCAL MODULES WITH THE NEED TO BE USED BOTH INSIDE AND OUTSIDE BAZEL

+ +

When using a monorepo it’s common to have modules that we want to use locally and +publish to an external package repository. This can be achieved using a js_library rule +with a package_name attribute defined inside the local package BUILD file. However, +if the project relies on the local package dependency with file:, this could introduce a +race condition with the npm_install rule.

+ +

In order to overcome it, a link will be created to the package BUILD file from the +npm external Bazel repository, which require us to complete a last step which is writing +the expected targets on that same BUILD file to be later used by the npm_install +rule, which are: <package_name__files>, <package_name__nested_node_modules>, +<package_name__contents>, <package_name__typings> and the last +one just <package_name>.

+ +

If you doubt what those targets should look like, check the +generated BUILD file for a given node module.

+

ATTRIBUTES

name

@@ -1018,6 +1037,18 @@

manual_build_file_contents

Defaults to ""

+

npm_command

+ +

(String): The npm command to run, to install dependencies.

+ +
        See npm docs <https://docs.npmjs.com/cli/v6/commands>
+        
+        In particular, for "ci" it says:
+        > If dependencies in the package lock do not match those in package.json, npm ci will exit with an error, instead of updating the package lock.
+
+ +

Defaults to "ci"

+

package_json

(Label, mandatory)

@@ -1250,9 +1281,9 @@

yarn_install

USAGE

-yarn_install(name, args, data, environment, included_files, manual_build_file_contents,
-             package_json, quiet, repo_mapping, strict_visibility, symlink_node_modules, timeout,
-             use_global_yarn_cache, yarn_lock)
+yarn_install(name, args, data, environment, frozen_lockfile, included_files,
+             manual_build_file_contents, package_json, quiet, repo_mapping, strict_visibility,
+             symlink_node_modules, timeout, use_global_yarn_cache, yarn_lock)

Runs yarn install during workspace setup.

@@ -1261,6 +1292,24 @@

yarn_install

set to another value in the environment attribute). Scripts may use to this to check if yarn is being run by the yarn_install repository rule.

+

LOCAL MODULES WITH THE NEED TO BE USED BOTH INSIDE AND OUTSIDE BAZEL

+ +

When using a monorepo it’s common to have modules that we want to use locally and +publish to an external package repository. This can be achieved using a js_library rule +with a package_name attribute defined inside the local package BUILD file. However, +if the project relies on the local package dependency with link:, this could introduce a +race condition with the yarn_install rule.

+ +

In order to overcome it, a link will be created to the package BUILD file from the +npm external Bazel repository, which require us to complete a last step which is writing +the expected targets on that same BUILD file to be later used by the yarn_install +rule, which are: <package_name__files>, <package_name__nested_node_modules>, +<package_name__contents>, <package_name__typings> and the last +one just <package_name>.

+ +

If you doubt what those targets should look like, check the +generated BUILD file for a given node module.

+

ATTRIBUTES

name

@@ -1296,6 +1345,21 @@

environment

Defaults to {}

+

frozen_lockfile

+ +

(Boolean): Use the --frozen-lockfile flag for yarn.

+ +

Don’t generate a yarn.lock lockfile and fail if an update is needed.

+ +

This flag enables an exact install of the version that is specified in the yarn.lock +file. This helps to have reproducible builds across builds.

+ +

To update a dependency or install a new one run the yarn install command with the +vendored yarn binary. bazel run @nodejs//:yarn install. You can pass the options like +bazel run @nodejs//:yarn install -- -D <dep-name>.

+ +

Defaults to True

+

included_files

(List of strings): List of file extensions to be included in the npm package targets.

diff --git a/docs/Built-ins.md b/docs/Built-ins.md index bd7ec7d1af..d2e78262c4 100755 --- a/docs/Built-ins.md +++ b/docs/Built-ins.md @@ -823,8 +823,9 @@ Defaults to `[]` **USAGE** 
-npm_install(name, args, data, environment, included_files, manual_build_file_contents, package_json,
-            package_lock_json, quiet, repo_mapping, strict_visibility, symlink_node_modules, timeout)
+npm_install(name, args, data, environment, included_files, manual_build_file_contents, npm_command,
+            package_json, package_lock_json, quiet, repo_mapping, strict_visibility,
+            symlink_node_modules, timeout)
Runs npm install during workspace setup. @@ -833,6 +834,25 @@ This rule will set the environment variable `BAZEL_NPM_INSTALL` to '1' (unless i set to another value in the environment attribute). Scripts may use to this to check if yarn is being run by the `npm_install` repository rule. + +**LOCAL MODULES WITH THE NEED TO BE USED BOTH INSIDE AND OUTSIDE BAZEL** + +When using a monorepo it's common to have modules that we want to use locally and +publish to an external package repository. This can be achieved using a `js_library` rule +with a `package_name` attribute defined inside the local package `BUILD` file. However, +if the project relies on the local package dependency with `file:`, this could introduce a +race condition with the `npm_install` rule. + +In order to overcome it, a link will be created to the package `BUILD` file from the +npm external Bazel repository, which require us to complete a last step which is writing +the expected targets on that same `BUILD` file to be later used by the `npm_install` +rule, which are: ``, ``, +``, `` and the last +one just ``. + +If you doubt what those targets should look like, check the +generated `BUILD` file for a given node module. + **ATTRIBUTES** @@ -904,6 +924,17 @@ fine grained npm dependencies. Defaults to `""` +

npm_command

+ +(*String*): The npm command to run, to install dependencies. + + See npm docs + + In particular, for "ci" it says: + > If dependencies in the package lock do not match those in package.json, npm ci will exit with an error, instead of updating the package lock. + +Defaults to `"ci"` +

package_json

(*Label, mandatory*) @@ -1157,9 +1188,9 @@ Defaults to `{}` **USAGE** 
-yarn_install(name, args, data, environment, included_files, manual_build_file_contents,
-             package_json, quiet, repo_mapping, strict_visibility, symlink_node_modules, timeout,
-             use_global_yarn_cache, yarn_lock)
+yarn_install(name, args, data, environment, frozen_lockfile, included_files,
+             manual_build_file_contents, package_json, quiet, repo_mapping, strict_visibility,
+             symlink_node_modules, timeout, use_global_yarn_cache, yarn_lock)
Runs yarn install during workspace setup. @@ -1168,6 +1199,25 @@ This rule will set the environment variable `BAZEL_YARN_INSTALL` to '1' (unless set to another value in the environment attribute). Scripts may use to this to check if yarn is being run by the `yarn_install` repository rule. + +**LOCAL MODULES WITH THE NEED TO BE USED BOTH INSIDE AND OUTSIDE BAZEL** + +When using a monorepo it's common to have modules that we want to use locally and +publish to an external package repository. This can be achieved using a `js_library` rule +with a `package_name` attribute defined inside the local package `BUILD` file. However, +if the project relies on the local package dependency with `link:`, this could introduce a +race condition with the `yarn_install` rule. + +In order to overcome it, a link will be created to the package `BUILD` file from the +npm external Bazel repository, which require us to complete a last step which is writing +the expected targets on that same `BUILD` file to be later used by the `yarn_install` +rule, which are: ``, ``, +``, `` and the last +one just ``. + +If you doubt what those targets should look like, check the +generated `BUILD` file for a given node module. + **ATTRIBUTES** @@ -1205,6 +1255,21 @@ Defaults to `[]` Defaults to `{}` +

frozen_lockfile

+ +(*Boolean*): Use the `--frozen-lockfile` flag for yarn. + +Don't generate a `yarn.lock` lockfile and fail if an update is needed. + +This flag enables an exact install of the version that is specified in the `yarn.lock` +file. This helps to have reproducible builds across builds. + +To update a dependency or install a new one run the `yarn install` command with the +vendored yarn binary. `bazel run @nodejs//:yarn install`. You can pass the options like +`bazel run @nodejs//:yarn install -- -D `. + +Defaults to `True` +

included_files

(*List of strings*): List of file extensions to be included in the npm package targets. diff --git a/docs/Karma.md b/docs/Karma.md new file mode 100755 index 0000000000..b389b8f411 --- /dev/null +++ b/docs/Karma.md @@ -0,0 +1,235 @@ +--- +title: Karma +layout: default +toc: true +nav: rule +--- + +# Karma rules for Bazel + +The Karma rules run karma tests with Bazel. + + +## Installation + +Add the `@bazel/karma` npm package to your `devDependencies` in `package.json`. + +Now add this to your `WORKSPACE` to install the Karma dependencies: + +```python +# Fetch transitive Bazel dependencies of @bazel/karma +load("@npm//@bazel/karma:package.bzl", "npm_bazel_karma_dependencies") +npm_bazel_karma_dependencies() +``` + +This installs the `io_bazel_rules_webtesting` repository, if you haven't installed it earlier. + +Finally, configure the rules_webtesting: + +```python +# Set up web testing, choose browsers we can test on +load("@io_bazel_rules_webtesting//web:repositories.bzl", "web_test_repositories") + +web_test_repositories() + +load("@io_bazel_rules_webtesting//web/versioned:browsers-0.3.2.bzl", "browser_repositories") + +browser_repositories( + chromium = True, + firefox = True, +) +``` + + +## Installing with self-managed dependencies + +If you didn't use the `yarn_install` or `npm_install` rule to create an `npm` workspace, you'll have to declare a rule in your root `BUILD.bazel` file to execute karma: + +```python +# Create a karma rule to use in ts_web_test_suite karma +# attribute when using self-managed dependencies +nodejs_binary( + name = "karma/karma", + entry_point = "//:node_modules/karma/bin/karma", + # Point bazel to your node_modules to find the entry point + node_modules = ["//:node_modules"], +) +``` + + + +## karma_web_test + +**USAGE** + +
+karma_web_test(srcs, deps, data, configuration_env_vars, bootstrap, runtime_deps, static_files,
+               config_file, tags, peer_deps, kwargs)
+
+ +Runs unit tests in a browser with Karma. + +When executed under `bazel test`, this uses a headless browser for speed. +This is also because `bazel test` allows multiple targets to be tested together, +and we don't want to open a Chrome window on your machine for each one. Also, +under `bazel test` the test will execute and immediately terminate. + +Running under `ibazel test` gives you a "watch mode" for your tests. The rule is +optimized for this case - the test runner server will stay running and just +re-serve the up-to-date JavaScript source bundle. + +To debug a single test target, run it with `bazel run` instead. This will open a +browser window on your computer. Also you can use any other browser by opening +the URL printed when the test starts up. The test will remain running until you +cancel the `bazel run` command. + +This rule will use your system Chrome by default. In the default case, your +environment must specify CHROME_BIN so that the rule will know which Chrome binary to run. +Other `browsers` and `customLaunchers` may be set using the a base Karma configuration +specified in the `config_file` attribute. + +By default we open a headless Chrome. To use a real Chrome browser window, you can pass +`--define DISPLAY=true` to Bazel, along with `configuration_env_vars = ["DISPLAY"]` on +`karma_web_test`. + + +**PARAMETERS** + + +

srcs

+ +A list of JavaScript test files + +Defaults to `[]` + +

deps

+ +Other targets which produce JavaScript such as `ts_library` + +Defaults to `[]` + +

data

+ +Runtime dependencies + +Defaults to `[]` + +

configuration_env_vars

+ +Pass these configuration environment variables to the resulting binary. +Chooses a subset of the configuration environment variables (taken from ctx.var), which also +includes anything specified via the --define flag. +Note, this can lead to different outputs produced by this rule. + +Defaults to `[]` + +

bootstrap

+ +JavaScript files to include *before* the module loader (require.js). +For example, you can include Reflect,js for TypeScript decorator metadata reflection, +or UMD bundles for third-party libraries. + +Defaults to `[]` + +

runtime_deps

+ +Dependencies which should be loaded after the module loader but before the srcs and deps. +These should be a list of targets which produce JavaScript such as `ts_library`. +The files will be loaded in the same order they are declared by that rule. + +Defaults to `[]` + +

static_files

+ +Arbitrary files which are available to be served on request. +Files are served at: +`/base/<WORKSPACE_NAME>/<path-to-file>`, e.g. +`/base/npm_bazel_typescript/examples/testing/static_script.js` + +Defaults to `[]` + +

config_file

+ +User supplied Karma configuration file. Bazel will override +certain attributes of this configuration file. Attributes that are +overridden will be outputted to the test log. + +Defaults to `None` + +

tags

+ +Standard Bazel tags, this macro adds tags for ibazel support + +Defaults to `[]` + +

peer_deps

+ +list of peer npm deps required by karma_web_test + +Defaults to `["@npm//jasmine-core", "@npm//karma", "@npm//karma-chrome-launcher", "@npm//karma-firefox-launcher", "@npm//karma-jasmine", "@npm//karma-requirejs", "@npm//karma-sourcemap-loader", "@npm//requirejs"]` + +

kwargs

+ +Passed through to `karma_web_test` + + + + + +## karma_web_test_suite + +**USAGE** + +
+karma_web_test_suite(name, browsers, web_test_data, wrapped_test_tags, kwargs)
+
+ +Defines a test_suite of web_test targets that wrap a karma_web_test target. + +This macro accepts all parameters in karma_web_test and adds additional parameters +for the suite. See karma_web_test docs for all karma_web_test. + +The wrapping macro is `web_test_suite` which comes from rules_websting: +https://github.com/bazelbuild/rules_webtesting/blob/master/web/web.bzl. + + +**PARAMETERS** + + +

name

+ +The base name of the test + + + +

browsers

+ +A sequence of labels specifying the browsers to use. + +Defaults to `None` + +

web_test_data

+ +Data dependencies for the wrapper web_test targets. + +Defaults to `[]` + +

wrapped_test_tags

+ +A list of test tag strings to use for the wrapped +karma_web_test target. + +Defaults to `["manual", "noci"]` + +

kwargs

+ +Arguments for the wrapped karma_web_test target. + + + + diff --git a/docs/install.html b/docs/install.html index d4db6cf114..f152d8653d 100755 --- a/docs/install.html +++ b/docs/install.html @@ -187,8 +187,8 @@

Custom installation

load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
 http_archive(
     name = "build_bazel_rules_nodejs",
-    sha256 = "f2194102720e662dbf193546585d705e645314319554c6ce7e47d8b59f459e9c",
-    urls = ["https://github.com/bazelbuild/rules_nodejs/releases/download/2.2.2/rules_nodejs-2.2.2.tar.gz"],
+    sha256 = "290b659e7a6323e442db922175a4838e4ac622509f9e9fa0dd16b7ca30377d68",
+    urls = ["https://github.com/bazelbuild/rules_nodejs/releases/download/3.0.0-rc.0/rules_nodejs-3.0.0-rc.0.tar.gz"],
 )
 
 load("@build_bazel_rules_nodejs//:index.bzl", "node_repositories")