deps: upgrade npm to 5.0.0

PR-URL: https://github.com/nodejs/node/pull/13276
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Jeremiah Senkpiel <fishrock123@rocketmail.com>

1 files changed, 9 insertions, 176 deletions

diff --git a/deps/npm/doc/cli/npm-shrinkwrap.md b/deps/npm/doc/cli/npm-shrinkwrap.md
index ae04bd02bb..4c223a86cc 100644
--- a/deps/npm/doc/cli/npm-shrinkwrap.md
+++ b/deps/npm/doc/cli/npm-shrinkwrap.md
@@ -1,4 +1,4 @@
-npm-shrinkwrap(1) -- Lock down dependency versions
+npm-shrinkwrap(1) -- Lock down dependency versions for publication
 =====================================================
 
 ## SYNOPSIS
@@ -7,181 +7,11 @@ npm-shrinkwrap(1) -- Lock down dependency versions
 
 ## DESCRIPTION
 
-This command locks down the versions of a package's dependencies so
-that you can control exactly which versions of each dependency will be
-used when your package is installed. The `package.json` file is still
-required if you want to use `npm install`.
-
-By default, `npm install` recursively installs the target's
-dependencies (as specified in `package.json`), choosing the latest
-available version that satisfies the dependency's semver pattern. In
-some situations, particularly when shipping software where each change
-is tightly managed, it's desirable to fully specify each version of
-each dependency recursively so that subsequent builds and deploys do
-not inadvertently pick up newer versions of a dependency that satisfy
-the semver pattern. Specifying specific semver patterns in each
-dependency's `package.json` would facilitate this, but that's not always
-possible or desirable, as when another author owns the npm package.
-It's also possible to check dependencies directly into source control,
-but that may be undesirable for other reasons.
-
-As an example, consider package A:
-
-    {
-      "name": "A",
-      "version": "0.1.0",
-      "dependencies": {
-        "B": "<0.1.0"
-      }
-    }
-
-package B:
-
-    {
-      "name": "B",
-      "version": "0.0.1",
-      "dependencies": {
-        "C": "<0.1.0"
-      }
-    }
-
-and package C:
-
-    {
-      "name": "C",
-      "version": "0.0.1"
-    }
-
-If these are the only versions of A, B, and C available in the
-registry, then a normal `npm install A` will install:
-
-    A@0.1.0
-    `-- B@0.0.1
-        `-- C@0.0.1
-
-However, if B@0.0.2 is published, then a fresh `npm install A` will
-install:
-
-    A@0.1.0
-    `-- B@0.0.2
-        `-- C@0.0.1
-
-assuming the new version did not modify B's dependencies. Of course,
-the new version of B could include a new version of C and any number
-of new dependencies. If such changes are undesirable, the author of A
-could specify a dependency on B@0.0.1. However, if A's author and B's
-author are not the same person, there's no way for A's author to say
-that he or she does not want to pull in newly published versions of C
-when B hasn't changed at all.
-
-In this case, A's author can run
-
-    npm shrinkwrap
-
-This generates `npm-shrinkwrap.json`, which will look something like this:
-
-    {
-      "name": "A",
-      "version": "0.1.0",
-      "dependencies": {
-        "B": {
-          "version": "0.0.1",
-          "from": "B@^0.0.1",
-          "resolved": "https://registry.npmjs.org/B/-/B-0.0.1.tgz",
-          "dependencies": {
-            "C": {
-              "version": "0.0.1",
-              "from": "org/C#v0.0.1",
-              "resolved": "git://github.com/org/C.git#5c380ae319fc4efe9e7f2d9c78b0faa588fd99b4"
-            }
-          }
-        }
-      }
-    }
-
-The shrinkwrap command has locked down the dependencies based on what's
-currently installed in `node_modules`.  The installation behavior is changed to:
-
-1. The module tree described by the shrinkwrap is reproduced. This means
-reproducing the structure described in the file, using the specific files
-referenced in "resolved" if available, falling back to normal package
-resolution using "version" if one isn't.
-
-2. The tree is walked and any missing dependencies are installed in the usual fashion.
-
-If `preshrinkwrap`, `shrinkwrap` or `postshrinkwrap` are in the `scripts` property of the
-`package.json`, they will be executed by running `npm shrinkwrap`.
-`preshrinkwrap` and `shrinkwrap` are executed before the shrinkwrap, `postshrinkwrap` is
-executed afterwards. For example to run some postprocessing on the generated file:
-
-    "scripts": { "postshrinkwrap": "node fix-shrinkwrap.js" }
-
-
-### Using shrinkwrapped packages
-
-Using a shrinkwrapped package is no different than using any other
-package: you can `npm install` it by hand, or add a dependency to your
-`package.json` file and `npm install` it.
-
-### Building shrinkwrapped packages
-
-To shrinkwrap an existing package:
-
-1. Run `npm install` in the package root to install the current
-   versions of all dependencies.
-2. Validate that the package works as expected with these versions.
-3. Run `npm shrinkwrap`, add `npm-shrinkwrap.json` to git, and publish
-   your package.
-
-To add or update a dependency in a shrinkwrapped package:
-
-1. Run `npm install` in the package root to install the current
-   versions of all dependencies.
-2. Add or update dependencies. `npm install --save` or `npm install --save-dev`
-   each new or updated package individually to update the `package.json` and
-   the shrinkwrap. Note that they must be explicitly named in order to be
-   installed: running `npm install` with no arguments will merely reproduce
-   the existing shrinkwrap.
-3. Validate that the package works as expected with the new
-   dependencies.
-4. Commit the new `npm-shrinkwrap.json`, and publish your package.
-
-You can use npm-outdated(1) to view dependencies with newer versions
-available.
-
-### Other Notes
-
-A shrinkwrap file must be consistent with the package's `package.json`
-file. `npm shrinkwrap` will fail if required dependencies are not
-already installed, since that would result in a shrinkwrap that
-wouldn't actually work. Similarly, the command will fail if there are
-extraneous packages (not referenced by `package.json`), since that would
-indicate that `package.json` is not correct.
-
-Starting with npm v4.0.1, `devDependencies` are included when you run
-`npm shrinkwrap` and follow the usual rules as to when they're installed.
-As of npm v3.10.8, if you run `npm install --only=production` or
-`npm install --production` with a shrinkwrap including your development
-dependencies they won't be installed. Similarly, if the environment
-variable `NODE_ENV` is `production` then they won't be installed. If you
-need compatibility with versions of npm prior to v3.10.8 or otherwise
-don't want them in your shrinkwrap you can exclude development
-dependencies with:
-`npm shrinkwrap --only=prod` or `npm shrinkwrap --production`.
-
-If shrinkwrapped package A depends on shrinkwrapped package B, B's
-shrinkwrap will not be used as part of the installation of A. However,
-because A's shrinkwrap is constructed from a valid installation of B
-and recursively specifies all dependencies, the contents of B's
-shrinkwrap will implicitly be included in A's shrinkwrap.
-
-### Caveats
-
-If you wish to lock down the specific bytes included in a package, for
-example to have 100% confidence in being able to reproduce a
-deployment or build, then you ought to check your dependencies into
-source control, or pursue some other mechanism that can verify
-contents rather than versions.
+This command repurposes `package-lock.json` into a publishable
+`npm-shrinkwrap.json` or simply creates a new one. The file created and updated
+by this command will then take precedence over any other existing or future
+`package-lock.json` files. For a detailed explanation of the design and purpose
+of package locks in npm, see npm-package-locks(5).
 
 ## SEE ALSO
 
@@ -189,4 +19,7 @@ contents rather than versions.
 * npm-run-script(1)
 * npm-scripts(7)
 * package.json(5)
+* npm-package-locks(5)
+* package-lock.json(5)
+* npm-shrinkwrap.json(5)
 * npm-ls(1)