docs: update docs for release

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

docs/Built-ins.md

@@ -823,8 +823,9 @@ Defaults to `[]`
 **USAGE**
 
 <pre>
-npm_install(<a href="#npm_install-name">name</a>, <a href="#npm_install-args">args</a>, <a href="#npm_install-data">data</a>, <a href="#npm_install-environment">environment</a>, <a href="#npm_install-included_files">included_files</a>, <a href="#npm_install-manual_build_file_contents">manual_build_file_contents</a>, <a href="#npm_install-package_json">package_json</a>,
-            <a href="#npm_install-package_lock_json">package_lock_json</a>, <a href="#npm_install-quiet">quiet</a>, <a href="#npm_install-repo_mapping">repo_mapping</a>, <a href="#npm_install-strict_visibility">strict_visibility</a>, <a href="#npm_install-symlink_node_modules">symlink_node_modules</a>, <a href="#npm_install-timeout">timeout</a>)
+npm_install(<a href="#npm_install-name">name</a>, <a href="#npm_install-args">args</a>, <a href="#npm_install-data">data</a>, <a href="#npm_install-environment">environment</a>, <a href="#npm_install-included_files">included_files</a>, <a href="#npm_install-manual_build_file_contents">manual_build_file_contents</a>, <a href="#npm_install-npm_command">npm_command</a>,
+            <a href="#npm_install-package_json">package_json</a>, <a href="#npm_install-package_lock_json">package_lock_json</a>, <a href="#npm_install-quiet">quiet</a>, <a href="#npm_install-repo_mapping">repo_mapping</a>, <a href="#npm_install-strict_visibility">strict_visibility</a>,
+            <a href="#npm_install-symlink_node_modules">symlink_node_modules</a>, <a href="#npm_install-timeout">timeout</a>)
 </pre>
 
 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: `<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**
 
 
@@ -904,6 +924,17 @@ fine grained npm dependencies.
 
 Defaults to `""`
 
+<h4 id="npm_install-npm_command">npm_command</h4>
+
+(*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"`
+
 <h4 id="npm_install-package_json">package_json</h4>
 
 (*<a href="https://bazel.build/docs/build-ref.html#labels">Label</a>, mandatory*)
@@ -1157,9 +1188,9 @@ Defaults to `{}`
 **USAGE**
 
 <pre>
-yarn_install(<a href="#yarn_install-name">name</a>, <a href="#yarn_install-args">args</a>, <a href="#yarn_install-data">data</a>, <a href="#yarn_install-environment">environment</a>, <a href="#yarn_install-included_files">included_files</a>, <a href="#yarn_install-manual_build_file_contents">manual_build_file_contents</a>,
-             <a href="#yarn_install-package_json">package_json</a>, <a href="#yarn_install-quiet">quiet</a>, <a href="#yarn_install-repo_mapping">repo_mapping</a>, <a href="#yarn_install-strict_visibility">strict_visibility</a>, <a href="#yarn_install-symlink_node_modules">symlink_node_modules</a>, <a href="#yarn_install-timeout">timeout</a>,
-             <a href="#yarn_install-use_global_yarn_cache">use_global_yarn_cache</a>, <a href="#yarn_install-yarn_lock">yarn_lock</a>)
+yarn_install(<a href="#yarn_install-name">name</a>, <a href="#yarn_install-args">args</a>, <a href="#yarn_install-data">data</a>, <a href="#yarn_install-environment">environment</a>, <a href="#yarn_install-frozen_lockfile">frozen_lockfile</a>, <a href="#yarn_install-included_files">included_files</a>,
+             <a href="#yarn_install-manual_build_file_contents">manual_build_file_contents</a>, <a href="#yarn_install-package_json">package_json</a>, <a href="#yarn_install-quiet">quiet</a>, <a href="#yarn_install-repo_mapping">repo_mapping</a>, <a href="#yarn_install-strict_visibility">strict_visibility</a>,
+             <a href="#yarn_install-symlink_node_modules">symlink_node_modules</a>, <a href="#yarn_install-timeout">timeout</a>, <a href="#yarn_install-use_global_yarn_cache">use_global_yarn_cache</a>, <a href="#yarn_install-yarn_lock">yarn_lock</a>)
 </pre>
 
 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: `<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**
 
 
@@ -1205,6 +1255,21 @@ Defaults to `[]`
 
 Defaults to `{}`
 
+<h4 id="yarn_install-frozen_lockfile">frozen_lockfile</h4>
+
+(*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`
+
 <h4 id="yarn_install-included_files">included_files</h4>
 
 (*List of strings*): List of file extensions to be included in the npm package targets.