[DOCS] docs for npm version state, incorrectly, that a version will be incremented by 1 #8637

Is there an existing issue for this?

• I have searched the existing issues

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

• This is a CLI Docs Problem.

Description of Problem

In the documentation for npm version, it says:

The newversion argument should be a valid semver string, a valid second argument to semver.inc (one of patch, minor, major, prepatch, preminor, premajor, prerelease), or from-git. In the second case, the existing version will be incremented by 1 in the specified field.

While this is usually the case, it is not always the case. Specifically, npm version patch against a prerelease version will remove the prerelease tag without incrementing the version. This is intentional and documented in node-semver. See https://github.com/npm/node-semver/blob/v7.7.2/classes/semver.js#L258, the section case 'patch':.

// If this is not a pre-release version, it will increment the patch.
// If it is a pre-release it will bump up to the same patch version.
// 1.2.0-5 patches to 1.2.0
// 1.2.0 patches to 1.2.1

Why care?

Because LLMs are reading these docs and don’t understand how version patch works. I have seen:

• LLMs telling a developer that npm version patch does not remove the prerelease version.
• That npm version patch always increments the 3rd number (patch) by 1.
• Proposing incorrect ways of removing the prerelease: npm version --preid='' prerelease (doesn’t do what the LLM thinks)
• Proposing increasingly ridiculous ways of fixing this (e.g. using sed, writing a script to parse the version number, etc.)

Potential Solution

Update the documentation to explain how npm version patch works.

Affected URL

https://docs.npmjs.com/cli/v11/commands/npm-version