docs: clarify npm version behavior with prerelease versions

[yashwantbezawada]

Summary

This PR clarifies the documentation for npm version to explicitly describe its behavior when the current version is a prerelease version.

Problem

The current documentation states that when using patch, minor, or major arguments, "the existing version will be incremented by 1 in the specified field." However, this is incomplete and misleading when the current version is a prerelease.

When the current version is a prerelease (e.g., 1.2.0-5), running npm version patch (or minor/major) will simply remove the prerelease suffix without incrementing the version number. The result would be 1.2.0, not 1.2.1.

This undocumented behavior has led to:

• Developer confusion when the version doesn't increment as expected
• Incorrect guidance from LLMs trained on the incomplete documentation

Solution

Added a note immediately after the existing sentence to clarify this behavior:

Note: If the current version is a prerelease version, patch, minor, and major will simply remove the prerelease suffix without incrementing the version number. For example, 1.2.0-5 becomes 1.2.0 with npm version patch, not 1.2.1.

Testing

The documentation change is straightforward and doesn't affect code behavior. The example provided matches the actual behavior of the semver.inc function from the node-semver package.

Fixes #8637

[yashwantbezawada]

Update on Documentation Accuracy

After thorough testing with actual npm version commands, I've updated the documentation to be more precise:

Actual behavior verified:

• 1.2.0-5 + npm version patch → 1.2.0 ✓ (removes prerelease, no increment)
• 1.2.0-5 + npm version minor → 1.2.0 (also removes, but only because patch=0)
• 1.2.0-5 + npm version major → 2.0.0 (increments because minor≠0)

The behavior of minor and major with prerelease versions is more complex and depends on the current version numbers. Therefore, the documentation now specifically mentions only patch, which has consistent behavior across all prerelease versions.

This matches the original issue report which was specifically about patch behavior and referenced the semver source code documentation for the patch case.

[wraithgar]

That note seems to break up the flow of the rest of that section, it may need to move to after that paragraph.