Update documentation related to NPM packages

The following changes is made in DOC:
- How to install npm package with bazel
- How to add new npm pacakges
- How to update npm packages

Change-Id: I6a126cc6a45a86040e54d181cdd79e942194790e

Documentation/dev-bazel.txt

@@ -514,10 +514,11 @@ Start by checking that the license and file types of the bundle are acceptable:
   package=some-npm-package
   version=1.2.3
 
-  npm install -g license-checker && \
+  # Note - yarn must be installed before running the following commands
+  yarn global add license-checker && \
   rm -rf /tmp/$package-$version && mkdir -p /tmp/$package-$version && \
   cd /tmp/$package-$version && \
-  npm install $package@$version && \
+  yarn add $package@$version && \
   license-checker | grep licenses: | sort -u
 ----
 
@@ -540,41 +541,44 @@ Next, check the file types:
 If you see anything that looks like a native library or binary, then we can't
 use the bundle.
 
-If everything looks good, create the bundle, and note the SHA-1:
-[source,bash]
+If everything looks good, install the package with the following command:
+[source, bash]
 ----
-  $gerrit_repo/tools/js/npm_pack.py $package $version && \
-  sha1sum $package-$version.tgz
+# Add to ui_npm. Other packages.json can be updated in the same way
+cd $gerrit_repo/polygerrit-ui/app
+bazel run @nodejs//:yarn add $package
 ----
 
-This creates a file named `$package-$version.tgz` in your working directory.
+Update the `polygerrit-ui/app/node_modules_licenses/licenses.ts` file. You should add licenses
+for the package itself and for all transitive depndencies. If you forgot to add a license, the
+`Documentation:check_licenses` test will fail.
 
-Any project maintainer can upload this file to the
-link:https://console.cloud.google.com/storage/browser/gerrit-maven/npm-packages[storage
-bucket,role=external,window=_blank].
+After the update, commit all changes to the repository (including `yarn.lock`).
 
-Finally, add the new binary to the build process:
-----
-  # WORKSPACE
-  npm_binary(
-      name = "some-npm-package",
-      repository = GERRIT,
-  )
+[NOTE]
+====
+If a npm package has transitive dependencies (or just several files) with a not allowed
+license and you can't avoid use it in release, then you can add this package.
+For example some packages contain demo-code with a different license. Another example - optional
+dependencies, which are not needed to build polygerrit, but they are installed together with
+the package anyway.
 
-  # lib/js/npm.bzl
-  NPM_VERSIONS = {
-    ...
-    "some-npm-package": "1.2.3",
-  }
+In this case you should exclude all files and/or transitive dependencies with a not allowed license.
+Adding such package requires additional updates:
 
-  NPM_SHA1S = {
-    ...
-    "some-npm-package": "<sha1>",
-  }
-----
+- Add dependencies (or files) to the license.ts with an appropriate license marked with
+`allowed: false`.
 
-To use the binary from the Bazel build, you need to use the `run_npm_binary.py`
-wrapper script. For an example, see the use of `crisper` in `tools/bzl/js.bzl`.
+- update package.json postinstall script to remove all non-allowed files (if you don't
+update postinstall script, `Documentation:check_licenses` test will fail.)
+====
+
+=== Update NPM Binaries
+To update a NPM binary the same actions as for a new one must be done (check licenses,
+update `licenses.ts` file, etc...). The only difference is a command to install a package: instead
+of `bazel run @nodejs//:yarn add $package` you should run the `bazel run @nodejs//:yarn upgrade ...`
+command with correct arguments. You can find the list of arguments in the
+link:https://classic.yarnpkg.com/en/docs/cli/upgrade/[yarn upgrade doc,role=external,window=_blank].
 
 
 

polygerrit-ui/README.md

@@ -12,6 +12,23 @@ to get and install Bazel.
 
 ## Installing [Node.js](https://nodejs.org/en/download/) and npm packages
 
+**Note**: Switch between an old branch with bower_components and a new branch with ui-npm
+packages (or vice versa) can lead to some build errors. To avoid such errors clean up the build
+repository:
+```sh
+rm -rf node_modules/ \
+    polygerrit-ui/node_modules/ \
+    polygerrit-ui/app/node_modules \
+    tools/node_tools/node_modules
+
+bazel clean
+```
+
+If it doesn't help also try to run
+```sh
+bazel clean --expunge
+```
+
 The minimum nodejs version supported is 8.x+
 
 ```sh
@@ -29,15 +46,28 @@ All other platforms:
 
 or use [nvm - Node Version Manager](https://github.com/nvm-sh/nvm).
 
-Various steps below require installing additional npm packages. The full list of
-dependencies can be installed with:
+Various steps below require installing additional npm packages. To start developing, it is enough
+to install only top-level packages with the following command: 
 
 ```sh
-npm install
+# Install packages from root-level packages.json
+bazel fetch @npm//:node_modules
 ```
 
-It may complain about a missing `typescript@2.3.4` peer dependency, which is
-harmless.
+All other packages are installed by bazel when needed. If you want to install them manually, run the
+following commands:
+```sh
+# Install packages from polygerrit-ui/app/packages.json
+bazel fetch @ui_npm//:node_modules
+
+# Install packages from polygerrit-ui/packages.json
+bazel fetch @ui_dev_npm//:node_modules
+
+# Install packages from tools/node_tools/packages.json
+bazel fetch @ui_dev_npm//:node_modules
+```
+
+More information for installing and using nodejs rules can be found here https://bazelbuild.github.io/rules_nodejs/install.html
 
 ## Serving files locally
 
@@ -110,11 +140,6 @@ $(bazel info output_base)/external/local_jdk/bin/java \
 
 ## Running Tests
 
-This step requires the `web-component-tester` npm module.
-
-Note: it may be necessary to add the options `--unsafe-perm=true --allow-root`
-to the `npm install` command to avoid file permission errors.
-
 For daily development you typically only want to run and debug individual tests.
 Run the local [Go proxy server](#go-server) and navigate for example to
 <http://localhost:8081/elements/shared/gr-account-entry/gr-account-entry_test.html>.