fix(release): apply preid to dependent patch bumps (#35381)

## Current Behavior
When running \`nx release version --preid rc\` with a project filter,
projects with a dependent patch bump (from another project being bumped)
do not have the preid applied. semver.inc('1.0.0', 'patch', 'rc')
returns '1.0.1' because semver silently ignores preid for non-prerelease
specifiers.

## Expected Behavior
The preid is applied to dependent patch bumps, so dependents get
'0.0.2-rc.0' instead of '0.0.2'. The fix adds `applyPreidToBumpType`
which converts patch to prepatch, minor to preminor, and major to
premajor when a preid is set.

## Related Issue(s)
Fixes #33488

Author: jaysoo

astro-docs/src/content/docs/guides/Nx Release/update-dependents.mdoc

@@ -47,3 +47,64 @@ For example, if `project-b` is bumped to version `2.1.0`, `project-a` will be up
   }
 }
 ```
+
+### Propagating `--preid` to dependent bumps
+
+Side-effectful bumps are always plain patch versions by default, even when the project that triggered them is being released as a prerelease.
+For example, run:
+
+```shell
+nx release version prepatch --preid rc --projects project-b
+```
+
+`project-b` moves from `2.0.0` to `2.0.1-rc.0`, but `project-a` still receives a stable side-effectful patch to `1.0.1`:
+
+```json
+// project-a after (default behavior)
+{
+  "name": "project-a",
+  "version": "1.0.1",
+  "dependencies": {
+    "project-b": "2.0.1-rc.0"
+  }
+}
+```
+
+That default reflects a deliberate tradeoff. Consuming a prerelease build of a dependency doesn't necessarily mean the dependent itself is a prerelease, and keeping side-effectful bumps on stable versions allows them to ship without promoting every project up the graph into a prerelease.
+
+To propagate the `--preid` value through to dependents, enable `version.applyPreidToDependents` in `nx.json`:
+
+```json
+{
+  "release": {
+    "version": {
+      "updateDependents": "always",
+      "applyPreidToDependents": true
+    }
+  }
+}
+```
+
+With this option enabled and `--preid rc` set, `project-a` receives a `prepatch` bump using the same preid:
+
+```json
+// project-a after (applyPreidToDependents: true)
+{
+  "name": "project-a",
+  "version": "1.0.1-rc.0",
+  "dependencies": {
+    "project-b": "2.0.1-rc.0"
+  }
+}
+```
+
+#### When to enable it
+
+Enable `applyPreidToDependents` when:
+
+- You publish a set of packages that release together (even if versioned independently) and want a single `nx release ... --preid rc` invocation to produce a consistent prerelease across all of them.
+- Your downstream users install all affected packages as a set and would be surprised to see a stable-version dependent pick up a prerelease dependency.
+
+Leave it off (the default) when a stable `1.0.1` of `project-a` depending on an `rc` of `project-b` is a valid, intentional release for you. Prerelease dependencies shouldn't automatically promote their consumers into prereleases.
+
+The option can also be set per release group under `release.groups.<group>.version.applyPreidToDependents` to scope the behavior to only certain groups.

astro-docs/src/content/docs/reference/nx-json.mdoc

@@ -591,6 +591,12 @@ Some important changes in Nx 22:
 - `releaseTag.strictPreid` now defaults to `true`
 - Fixed Release Group Release Tag Pattern now defaults to `{releaseGroupName}-v{version}`
 
+#### Propagating `--preid` to dependent bumps
+
+When versioning with `--preid`, the implicit patch bumps given to dependents (and to other projects in a fixed release group) are stable patches by default. That means `project-b` being bumped to `2.0.1-rc.0` still bumps its dependent `project-a` to `1.0.1`, not `1.0.1-rc.0`.
+
+Set `version.applyPreidToDependents` to `true` if you want the `--preid` value to flow through to those side-effectful bumps instead. It can also be set per release group under `release.groups.<group>.version.applyPreidToDependents`. See [Update Dependents](/docs/guides/nx-release/update-dependents#propagating-preid-to-dependent-bumps) for the full walkthrough and guidance on when to enable it.
+
 ### Changelog
 
 The `changelog` property configures the changelog phase of the release process. It is used to generate a changelog for your projects, and commit it to your repository.

packages/nx/schemas/nx-schema.json

@@ -1175,6 +1175,11 @@
           "description": "Whether to strictly follow SemVer V2 spec for 0.x versions where breaking changes bump the minor version (instead of major), and new features bump the patch version (instead of minor). When enabled: 'major' bumps become 'minor' bumps for 0.x versions, 'minor' bumps become 'patch' bumps for 0.x versions. Versions 1.0.0 and above are unaffected. This is false by default for backward compatibility.",
           "default": false
         },
+        "applyPreidToDependents": {
+          "type": "boolean",
+          "description": "Whether to apply the --preid value to the implicit patch bumps given to dependents (and other projects in a fixed release group) when a dependency is versioned. When true, those dependents become prepatch bumps using the same preid (e.g. 1.0.1-rc.0 instead of 1.0.1). This is false by default for backward compatibility.",
+          "default": false
+        },
         "versionActions": {
           "type": "string",
           "description": "The path to the version actions implementation to use for releasing all projects by default. This can also be overridden on the release group and project levels.",
@@ -1297,6 +1302,11 @@
           "description": "Whether to apply the common convention for 0.x versions where breaking changes bump the minor version (instead of major), and new features bump the patch version (instead of minor). When enabled: 'major' bumps become 'minor' bumps for 0.x versions, 'minor' bumps become 'patch' bumps for 0.x versions. Versions 1.0.0 and above are unaffected. This is false by default for backward compatibility.",
           "default": false
         },
+        "applyPreidToDependents": {
+          "type": "boolean",
+          "description": "Whether to apply the --preid value to the implicit patch bumps given to dependents (and other projects in a fixed release group) when a dependency is versioned. When true, those dependents become prepatch bumps using the same preid (e.g. 1.0.1-rc.0 instead of 1.0.1). This is false by default for backward compatibility.",
+          "default": false
+        },
         "versionActions": {
           "type": "string",
           "description": "The path to the version actions implementation to use for releasing all projects by default. This can also be overridden on the release group and project levels.",

packages/nx/src/command-line/release/utils/release-graph.ts

@@ -45,6 +45,7 @@ export interface FinalConfigForProject {
   preserveLocalDependencyProtocols: NxReleaseVersionConfiguration['preserveLocalDependencyProtocols'];
   preserveMatchingDependencyRanges: NxReleaseVersionConfiguration['preserveMatchingDependencyRanges'];
   adjustSemverBumpsForZeroMajorVersion: NxReleaseVersionConfiguration['adjustSemverBumpsForZeroMajorVersion'];
+  applyPreidToDependents: NxReleaseVersionConfiguration['applyPreidToDependents'];
   versionActionsOptions: NxReleaseVersionConfiguration['versionActionsOptions'];
   manifestRootsToUpdate: Array<
     Exclude<
@@ -918,6 +919,17 @@ Valid values are: ${validReleaseVersionPrefixes
       releaseGroupVersionConfig?.adjustSemverBumpsForZeroMajorVersion ??
       false;
 
+    /**
+     * applyPreidToDependents
+     *
+     * Defaults to false to preserve the long-standing behavior where dependents
+     * of a prerelease-bumped project get a stable patch bump unless opted in.
+     */
+    const applyPreidToDependents =
+      projectVersionConfig?.applyPreidToDependents ??
+      releaseGroupVersionConfig?.applyPreidToDependents ??
+      false;
+
     /**
      * fallbackCurrentVersionResolver, defaults to disk when performing a first release, otherwise undefined
      */
@@ -963,6 +975,7 @@ Valid values are: ${validReleaseVersionPrefixes
       preserveLocalDependencyProtocols,
       preserveMatchingDependencyRanges,
       adjustSemverBumpsForZeroMajorVersion,
+      applyPreidToDependents,
       versionActionsOptions,
       manifestRootsToUpdate,
       dockerOptions,

packages/nx/src/command-line/release/version/release-group-processor.ts

@@ -406,7 +406,7 @@ export class ReleaseGroupProcessor {
           if (!this.bumpedProjects.has(project)) {
             await this.bumpVersionForProject(
               project,
-              'patch',
+              this.applyPreidToBumpType('patch', project),
               'OTHER_PROJECT_IN_FIXED_GROUP_WAS_BUMPED_DUE_TO_DEPENDENCY',
               {}
             );
@@ -894,7 +894,7 @@ export class ReleaseGroupProcessor {
         if (!this.bumpedProjects.has(dependent)) {
           await this.bumpVersionForProject(
             dependent,
-            'patch',
+            this.applyPreidToBumpType('patch', dependent),
             'DEPENDENCY_WAS_BUMPED',
             {}
           );
@@ -960,8 +960,44 @@ export class ReleaseGroupProcessor {
     releaseGroup: ReleaseGroupWithName,
     dependencyBumpType: SemverBumpType
   ): SemverBumpType {
-    const sideEffectBump = 'patch';
-    return sideEffectBump as SemverBumpType;
+    // Any project in the group can be used to resolve the applyPreidToDependents
+    // setting, since it is a group/workspace level option.
+    const anyProject = releaseGroup.projects[0];
+    return this.applyPreidToBumpType('patch', anyProject);
+  }
+
+  /**
+   * When a preid is set (e.g. --preid rc) and the project has opted in via
+   * `applyPreidToDependents`, convert a "patch" side-effect bump into a
+   * "prepatch" so that semver.inc() actually applies the preid.
+   * semver.inc('1.0.0', 'patch', 'rc') ignores preid and returns '1.0.1'.
+   * semver.inc('1.0.0', 'prepatch', 'rc') returns '1.0.1-rc.0' as expected.
+   */
+  private applyPreidToBumpType(
+    bumpType: SemverBumpType,
+    projectName: string
+  ): SemverBumpType {
+    if (
+      !this.options.preid ||
+      bumpType === 'none' ||
+      bumpType.startsWith('pre')
+    ) {
+      return bumpType;
+    }
+    const finalConfig = this.getCachedFinalConfigForProject(projectName);
+    if (!finalConfig.applyPreidToDependents) {
+      return bumpType;
+    }
+    switch (bumpType) {
+      case 'major':
+        return 'premajor';
+      case 'minor':
+        return 'preminor';
+      case 'patch':
+        return 'prepatch';
+      default:
+        return bumpType;
+    }
   }
 
   private getProjectDependents(project: string): Set<string> {

packages/nx/src/command-line/release/version/release-version.spec.ts

@@ -836,6 +836,140 @@ describe('releaseVersionGenerator (ported tests)', () => {
           `);
         });
 
+        it('should not apply preid to dependent patch bumps by default when --preid is set', async () => {
+          const { nxReleaseConfig, projectGraph, filters } =
+            await createNxReleaseConfigAndPopulateWorkspace(
+              tree,
+              `
+                __default__ ({ "projectsRelationship": "independent" }):
+                  - [email protected] [js]
+                  - [email protected] [js]
+                    -> depends on my-lib
+                  - [email protected] [js]
+                    -> depends on my-lib {devDependencies}
+              `,
+              {
+                version: {
+                  specifierSource: 'prompt',
+                  adjustSemverBumpsForZeroMajorVersion: true,
+                  updateDependents: 'auto',
+                },
+              },
+              undefined,
+              {
+                projects: ['my-lib'],
+              }
+            );
+
+          // Default behavior (applyPreidToDependents unset): dependents only
+          // get a stable patch bump even though the bumped project is a prerelease.
+          await releaseVersionGeneratorForTest(tree, {
+            nxReleaseConfig,
+            filters,
+            projectGraph,
+            userGivenSpecifier: 'prepatch' as SemverBumpType,
+            preid: 'rc',
+          });
+
+          expect(readJson(tree, 'my-lib/package.json')).toMatchInlineSnapshot(`
+            {
+              "name": "my-lib",
+              "version": "0.0.2-rc.0",
+            }
+          `);
+
+          expect(
+            readJson(tree, 'project-with-dependency-on-my-pkg/package.json')
+          ).toMatchInlineSnapshot(`
+            {
+              "dependencies": {
+                "my-lib": "0.0.2-rc.0",
+              },
+              "name": "project-with-dependency-on-my-pkg",
+              "version": "0.0.2",
+            }
+          `);
+          expect(
+            readJson(tree, 'project-with-devDependency-on-my-pkg/package.json')
+          ).toMatchInlineSnapshot(`
+            {
+              "devDependencies": {
+                "my-lib": "0.0.2-rc.0",
+              },
+              "name": "project-with-devDependency-on-my-pkg",
+              "version": "0.0.2",
+            }
+          `);
+        });
+
+        it('should apply preid to dependent patch bumps when applyPreidToDependents is enabled and --preid is set', async () => {
+          const { nxReleaseConfig, projectGraph, filters } =
+            await createNxReleaseConfigAndPopulateWorkspace(
+              tree,
+              `
+                __default__ ({ "projectsRelationship": "independent" }):
+                  - [email protected] [js]
+                  - [email protected] [js]
+                    -> depends on my-lib
+                  - [email protected] [js]
+                    -> depends on my-lib {devDependencies}
+              `,
+              {
+                version: {
+                  specifierSource: 'prompt',
+                  adjustSemverBumpsForZeroMajorVersion: true,
+                  updateDependents: 'auto',
+                  applyPreidToDependents: true,
+                },
+              },
+              undefined,
+              {
+                projects: ['my-lib'],
+              }
+            );
+
+          // With applyPreidToDependents: true, dependents that are only
+          // receiving a dependent patch bump are upgraded to prepatch so the
+          // preid is actually applied.
+          await releaseVersionGeneratorForTest(tree, {
+            nxReleaseConfig,
+            filters,
+            projectGraph,
+            userGivenSpecifier: 'prepatch' as SemverBumpType,
+            preid: 'rc',
+          });
+
+          expect(readJson(tree, 'my-lib/package.json')).toMatchInlineSnapshot(`
+            {
+              "name": "my-lib",
+              "version": "0.0.2-rc.0",
+            }
+          `);
+
+          expect(
+            readJson(tree, 'project-with-dependency-on-my-pkg/package.json')
+          ).toMatchInlineSnapshot(`
+            {
+              "dependencies": {
+                "my-lib": "0.0.2-rc.0",
+              },
+              "name": "project-with-dependency-on-my-pkg",
+              "version": "0.0.2-rc.0",
+            }
+          `);
+          expect(
+            readJson(tree, 'project-with-devDependency-on-my-pkg/package.json')
+          ).toMatchInlineSnapshot(`
+            {
+              "devDependencies": {
+                "my-lib": "0.0.2-rc.0",
+              },
+              "name": "project-with-devDependency-on-my-pkg",
+              "version": "0.0.2-rc.0",
+            }
+          `);
+        });
+
         it('should update dependents with a prepatch when creating a pre-release version', async () => {
           const { nxReleaseConfig, projectGraph, filters } =
             await createNxReleaseConfigAndPopulateWorkspace(

packages/nx/src/config/nx-json.ts

@@ -229,6 +229,17 @@ export interface NxReleaseVersionConfiguration {
    * This is false by default for backward compatibility.
    */
   adjustSemverBumpsForZeroMajorVersion?: boolean;
+  /**
+   * Whether to apply the --preid value to the implicit patch bumps given to
+   * dependents (and other projects in a fixed release group) when a dependency
+   * is versioned. When true, those dependents are bumped as a prepatch using
+   * the same preid, so a dependency moving to "1.2.3-rc.0" will bump its
+   * dependents to "1.0.1-rc.0" instead of "1.0.1".
+   *
+   * This is false by default for backward compatibility — consuming an RC of a
+   * dependency does not necessarily mean the consumer itself is an RC.
+   */
+  applyPreidToDependents?: boolean;
 }
 
 export interface NxReleaseChangelogConfiguration {