docs: clarify npm version behavior with prerelease versions (#8735)

yashwantbezawada · web-flow · commit 73688ca5eb98 · 2025-12-01T09:07:36.000-08:00
## 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
diff --git a/docs/lib/content/commands/npm-version.md b/docs/lib/content/commands/npm-version.md
@@ -21,6 +21,8 @@ The `newversion` argument should be a valid semver string, a valid second argume
 In the second case, the existing version will be incremented by 1 in the specified field.
 `from-git` will try to read the latest git tag, and use that as the new npm version.
 
+**Note:** If the current version is a prerelease version, `patch` will simply remove the prerelease suffix without incrementing the patch version number. For example, `1.2.0-5` becomes `1.2.0` with `npm version patch`, not `1.2.1`.
+
 If run in a git repo, it will also create a version commit and tag.
 This behavior is controlled by `git-tag-version` (see below), and can be disabled on the command line by running `npm --no-git-tag-version version`.
 It will fail if the working directory is not clean, unless the `-f` or `--force` flag is set.
