Improve documentation around package-lock.json conflict resolution

[cjones26]

Since npm v6, there has been no information in the documentation regarding package-lock.json conflict resolution. After a bit of research, I came across this npm/cli#4844 (comment) by @wraithgar stating that the https://github.com/npm/npm-merge-driver functionality has now been integrated directly into npm via the https://github.com/npm/parse-conflict-json package.

Though I tested and merge conflicts in package-lock.json were resolved automatically when performing an npm i in a project with package-lock conflicts, I think it's pretty unclear how the entire process works, including which conflict wins when resolved automatically.

I am guessing that the parse-conflict-json package utilizes the default algorithm specified in the README, but does this replicate what the npm-merge-driver did previously?

It also appears I am not the only one with this confusion as per this discussion here: https://gist.github.com/szemate/6fb69c8e3d8cce3efa9a6c922b337d98 -- specifically the comment by DaveVodrazka:

Here is a step by step example, that should make it extra clear:

Problem

My library has three dependencies, package a, b and c. My package.json looks like this:

{
  "a": "^1.0.0",
  "b": "^1.0.0",
  "c": "^1.0.0"
}

and my package-lock.json looks like this (notice missing ^):

{
  "a": "1.0.0",
  "b": "1.0.0",
  "c": "1.0.0"
}

This means, that all three dependencies are "locked" at version 1.0.0.

Now, some time has gone by and maintainers of my dependencies have published newer versions. In the npm repository the latest versions are now a: 1.2.1, b: 1.3.4 and c: 1.0.7.

I need to bump package c to version 1.0.7 to fix some bug. I run npm install c and merge changes. package.json now looks like this:

{
  "a": "^1.0.0",
  "b": "^1.0.0",
  "c": "^1.0.7"
}

and pakcage-lock.json like this:

{
  "a": "1.0.0",
  "b": "1.0.0",
  "c": "1.0.7"
}

Someone else decides to bump package b to fix a different bug. They checkout their own branch and run npm install b, which bumps pakcage b to 1.3.4. Their package.json looks like this:

{
  "a": "^1.0.0",
  "b": "^1.3.4",
  "c": "^1.0.0"
}

and pakcage-lock.json like this:

{
  "a": "1.0.0",
  "b": "1.3.4",
  "c": "1.0.0"
}

They try to merge, but run into a conflict. They easily resolve conflict in package.json like this:

{
  "a": "^1.0.0",
  "b": "^1.3.4",
  "c": "^1.0.7"
}

So that both package b and c are at the appropriate version. All that is left to do is to resolve conflict in the package-lock.json.

And this is where we run into the problem, because the package-lock.json that we should have locks versions like this:

{
  "a": "1.0.0",
  "b": "1.3.4",
  "c": "1.0.7"
}

But if you were to run npm install now, the pakcage-lock.json you'd end up with would lock these versions:

{
  "a": "1.2.1",
  "b": "1.3.4",
  "c": "1.0.7"
}

Notice that, while nobody bumped package a, we ended up with a new version "a": "1.2.1".

Explanation

Now why is that? Since the version in our package.json is set to "a": "^1.0.0", the ^ symbols tells npm to keep both minor and patch version up to date, ie. if there is newer minor or patch version, it will be downloaded and updated in package-lock.json.

Theoretically, this should not be a problem, because patch should never break anything and minor version update should always be backwards compatible, but since versioning is done by people and people are prone to making mistakes - this does not always hold true.

This is why running npm install to resolve package-lock.json conflits is not a bulletproof strategy.

I don't have a better solution and I do use this way of fixing the conflicts, but you should be aware of potential problems this may introduce.

[MylesBorins]

Thanks for opening this discussion. I'm pinging the CLI team to see where they think something like this should live.

[cjones26]

@MylesBorins what ended up being the consensus here?