[DOCS] Explain behavior of "npm install" w/r/t package versions in package-lock.json.

[damellis]

Is there an existing issue for this?

• I have searched the existing issues

This is a CLI Docs Enhancement, not another kind of Docs Enhancement.

• This is a CLI Docs Enhancement.

Description of Problem

The npm-install documentation for npm 8 doesn't explain the behavior of a no-argument "npm install" with respect to the package versions present in the package-lock.json file.

Potential Solution

Describe how a no-argument "npm install" decides which version of each package to install, when there is a package-lock.json file present. For example, this description from Kat Marchán:

The story about package.json vs package-lock.json is tricky: npm install does not ignore package.json versions, nor does it ignore the package-lock.json. What it does is verify that the package.json and package-lock.json correspond to each other. That is, if the semver versions described in package.json fit with the locked versions in package-lock.json, npm install will use the latter completely, just like npm ci would.

Now, ff you change package.json such that the versions in package-lock.json are no longer valid, your npm install will be treated as if you'd done npm install some-pkg@x.y.z, where x.y.z is the new version in the package.json for some-package.

Docs URL

https://docs.npmjs.com/cli/v8/commands/npm-install

[damellis]

Also, there are apparently some complications around tags and git tags that would be great to document as well.