nx-gradle-plugin-version-bump

name	nx-gradle-plugin-version-bump
description	Bump the dev.nx.gradle.project-graph plugin version. Use when updating the Gradle project graph plugin version across the codebase, creating the migration files, and updating migrations.json.
allowed-tools	Bash, Read, Write, Edit, Glob, Grep

Gradle Plugin Version Bump

Bumps the dev.nx.gradle.project-graph plugin to a new version. This is a recurring task that touches 5 files in an identical pattern every time.

Required Inputs

Collect these values from the master branch before starting:

1. NEW_VERSION - the version we want to bump to Example: OLD_VERSION: 0.1.15 => NEW_VERSION: 0.1.16 You can find this value by looking at the OLD_VERSION specified in packages/gradle/project-graph/build.gradle.kts in the version field.
   The NEW_VERSION will be the OLD_VERSION + 1.

2. NX_MIGRATION_VERSION - the version of Nx that will trigger our version bump migration Example: OLD_VERSION: 22.7.0-beta.0 => NEW_VERSION: 22.7.0-beta.1 You can find this value by looking at the nx version in package.json under devDependencies. The NEW_VERSION will be the OLD_VERSION + 1.

3. MIGRATION_FOLDER - the folder name under packages/gradle/src/migrations/ that will contain our migration files Example: NEW_VERSION: 22.7.0-beta.1 => MIGRATION_FOLDER: 22-7-0 Take the version and replace all the dots with hyphens and remove the beta or rc suffix.

Steps

1. Update the version constant

File: packages/gradle/src/utils/versions.ts

Change gradleProjectGraphVersion to the new version:

export const gradleProjectGraphVersion = 'NEW_VERSION';

2. Update build.gradle.kts

File: packages/gradle/project-graph/build.gradle.kts

Update the version on line 13:

version = "NEW_VERSION"

3. Create migration TypeScript file

File: packages/gradle/src/migrations/MIGRATION_FOLDER/change-plugin-version-NEW_VERSION.ts

Determine the previous version by reading the current gradleProjectGraphVersion from packages/gradle/src/utils/versions.ts before modifying it.

Template:

import { Tree, readNxJson } from '@nx/devkit';
import { hasGradlePlugin } from '../../utils/has-gradle-plugin';
import { addNxProjectGraphPlugin } from '../../generators/init/gradle-project-graph-plugin-utils';
import { updateNxPluginVersionInCatalogsAst } from '../../utils/version-catalog-ast-utils';

/* Change the plugin version to NEW_VERSION
 */
export default async function update(tree: Tree) {
  const nxJson = readNxJson(tree);
  if (!nxJson) {
    return;
  }
  if (!hasGradlePlugin(tree)) {
    return;
  }

  const gradlePluginVersionToUpdate = 'NEW_VERSION';

  // Update version in version catalogs using AST-based approach to preserve formatting
  await updateNxPluginVersionInCatalogsAst(tree, gradlePluginVersionToUpdate);

  // Then update in build.gradle(.kts) files
  await addNxProjectGraphPlugin(tree, gradlePluginVersionToUpdate);
}

4. Create migration documentation file

File: packages/gradle/src/migrations/MIGRATION_FOLDER/change-plugin-version-NEW_VERSION.md

Replace PREV_VERSION with the version that was current before this bump.

Template:

#### Change dev.nx.gradle.project-graph to version NEW_VERSION

Change dev.nx.gradle.project-graph to version NEW_VERSION in build file

#### Sample Code Changes

##### Before

\```text title="build.gradle"
plugins {
id "dev.nx.gradle.project-graph" version "PREV_VERSION"
}
\```

##### After

\```text title="build.gradle"
plugins {
id "dev.nx.gradle.project-graph" version "NEW_VERSION"
}
\```

5. Add migration entry to migrations.json

File: packages/gradle/migrations.json

Add a new entry at the end of the generators object (before the closing }), following the existing pattern:

"change-plugin-version-NEW_VERSION": {
  "version": "NX_MIGRATION_VERSION",
  "description": "Change dev.nx.gradle.project-graph to version NEW_VERSION in build file",
  "implementation": "./dist/src/migrations/MIGRATION_FOLDER/change-plugin-version-NEW_VERSION",
  "documentation": "./dist/src/migrations/MIGRATION_FOLDER/change-plugin-version-NEW_VERSION.md"
}

The migration key uses the version with hyphens replacing dots (e.g., 0-1-16). The paths are dist-prefixed because the published package ships only dist/, and documentation is how the entry references the step-4 file. Older entries also carry cli: "nx" (deprecated in the migrations schema) and the factory alias for implementation; the template uses the primary key and omits cli. For the general entry shape see the author-migration skill.

Verification

Run:

nx run-many -t test,build,lint -p gradle

Commit Convention

chore(gradle): bump gradle project graph plugin version to NEW_VERSION

Final Verification

Take a look at the most recent Gradle version bump PR and compare your changes to that. You should not be touching more or less files than the most recent version bump PR. If you do, ask for more information and stop all changes.