feat(core): log a note after an interactive migration run with skippe…

…d package updates (#16802)

docs/shared/core-features/automate-updating-dependencies.md

@@ -17,16 +17,16 @@ Updating happens in three steps:
 First, run the `migrate` command:
 
 ```shell
-nx migrate latest # same as nx migrate @nx/workspace@latest
+nx migrate latest # same as nx migrate nx@latest
 ```
 
 You can also specify the name of the package and the version:
 
 ```shell
-nx migrate @nx/workspace@version # you can also specify version
+nx migrate nx@version # you can also specify version
 ```
 
-This fetches the specified version of the `@nx/workspace` package, analyzes the dependencies and fetches all the dependent packages. The process keeps going until all the dependencies are resolved. This results in:
+This fetches the specified version of the `nx` package, analyzes the dependencies and fetches all the dependent packages. The process keeps going until all the dependencies are resolved. This results in:
 
 - The `package.json` being updated
 - A `migrations.json` being generated if there are pending migrations.

docs/shared/recipes/advanced-update.md

@@ -1,6 +1,37 @@
 # Advanced update process
 
-This is an advanced version of the [standard update process](/core-features/automate-updating-dependencies).
+This guide describes advanced scenarios when it comes to updating Nx and the workspaces dependencies. It starts with a summary of the [standard update process](/core-features/automate-updating-dependencies) and continues with those advanced use cases.
+
+## Updating to the latest Nx version
+
+The following steps are a summary of the [standard update process](/core-features/automate-updating-dependencies). For more information on each step, please visit that page.
+
+### Step 1: Updating dependencies and generating migrations
+
+First, run the `migrate` command:
+
+```shell
+nx migrate latest # same as nx migrate nx@latest
+```
+
+This performs the following changes:
+
+- Updates the versions of the relevant packages in the `package.json` file.
+- Generates a `migrations.json` if there are pending migrations.
+
+### Step 2: Running migrations
+
+The next step in the process involves using the `migrate` command to apply the migrations that were generated in the `migrations.json` file in the previous step. You can do so by running:
+
+```shell
+nx migrate --run-migrations
+```
+
+All changes to your source code will be unstaged and ready for you to review and commit yourself.
+
+### Step 3: Cleaning up
+
+After you run all the migrations, you can remove `migrations.json` and commit any outstanding changes.
 
 ## Managing migration steps
 

packages/nx/src/command-line/migrate/migrate.spec.ts

@@ -426,6 +426,7 @@ describe('Migration', () => {
           },
           '@my-company/lib-4': { version: '2.0.1', addToPackageJson: false },
         },
+        minVersionWithSkippedUpdates: undefined,
       });
     });
 
@@ -503,6 +504,7 @@ describe('Migration', () => {
           '@my-company/lib-1': { version: '3.0.0', addToPackageJson: false },
           '@my-company/lib-2': { version: '3.0.0', addToPackageJson: false },
         },
+        minVersionWithSkippedUpdates: undefined,
       });
     });
 
@@ -635,6 +637,7 @@ describe('Migration', () => {
             child2: { version: '3.0.0', addToPackageJson: false },
             child3: { version: '3.0.0', addToPackageJson: false },
           },
+          minVersionWithSkippedUpdates: undefined,
         });
         expect(enquirer.prompt).toHaveBeenCalledWith(
           expect.arrayContaining([
@@ -693,6 +696,7 @@ describe('Migration', () => {
             mypackage: { version: '2.0.0', addToPackageJson: false },
             child1: { version: '3.0.0', addToPackageJson: false },
           },
+          minVersionWithSkippedUpdates: '2.0.0',
         });
         expect(enquirer.prompt).toHaveBeenCalled();
       });
@@ -749,6 +753,7 @@ describe('Migration', () => {
             child2: { version: '3.0.0', addToPackageJson: false },
             child3: { version: '3.0.0', addToPackageJson: false },
           },
+          minVersionWithSkippedUpdates: undefined,
         });
         expect(enquirer.prompt).not.toHaveBeenCalled();
       });
@@ -831,6 +836,7 @@ describe('Migration', () => {
             child2: { version: '3.0.0', addToPackageJson: false },
             child3: { version: '3.0.0', addToPackageJson: false },
           },
+          minVersionWithSkippedUpdates: undefined,
         });
       });
 
@@ -913,6 +919,7 @@ describe('Migration', () => {
             pkg1: { version: '2.0.0', addToPackageJson: false },
             pkg2: { version: '2.0.0', addToPackageJson: false },
           },
+          minVersionWithSkippedUpdates: undefined,
         });
       });
 
@@ -961,6 +968,7 @@ describe('Migration', () => {
             mypackage: { version: '2.0.0', addToPackageJson: false },
             child1: { version: '3.0.0', addToPackageJson: false },
           },
+          minVersionWithSkippedUpdates: undefined,
         });
         expect(enquirer.prompt).toHaveBeenCalledWith(
           expect.arrayContaining([
@@ -1013,6 +1021,7 @@ describe('Migration', () => {
           packageUpdates: {
             mypackage: { version: '2.0.0', addToPackageJson: false },
           },
+          minVersionWithSkippedUpdates: undefined,
         });
         expect(enquirer.prompt).not.toHaveBeenCalled();
       });
@@ -1257,6 +1266,7 @@ describe('Migration', () => {
         packageUpdates: {
           parent: { version: '2.0.0', addToPackageJson: false },
         },
+        minVersionWithSkippedUpdates: '2.0.0',
       });
       expect(enquirer.prompt).toHaveBeenCalled();
     });

packages/nx/src/command-line/migrate/migrate.ts

@@ -137,6 +137,7 @@ export class Migrator {
   private readonly collectedVersions: Record<string, string> = {};
   private readonly promptAnswers: Record<string, boolean> = {};
   private readonly nxInstallation: NxJsonConfiguration['installation'] | null;
+  private minVersionWithSkippedUpdates: string | undefined;
 
   constructor(opts: MigratorOptions) {
     this.packageJson = opts.packageJson;
@@ -156,7 +157,11 @@ export class Migrator {
     });
 
     const migrations = await this.createMigrateJson();
-    return { packageUpdates: this.packageUpdates, migrations };
+    return {
+      packageUpdates: this.packageUpdates,
+      migrations,
+      minVersionWithSkippedUpdates: this.minVersionWithSkippedUpdates,
+    };
   }
 
   private async createMigrateJson() {
@@ -567,6 +572,15 @@ export class Migrator {
       },
     ]).then(({ shouldApply }: { shouldApply: boolean }) => {
       this.promptAnswers[promptKey] = shouldApply;
+
+      if (
+        !shouldApply &&
+        (!this.minVersionWithSkippedUpdates ||
+          lt(packageUpdate.version, this.minVersionWithSkippedUpdates))
+      ) {
+        this.minVersionWithSkippedUpdates = packageUpdate.version;
+      }
+
       return shouldApply;
     });
   }
@@ -1232,10 +1246,8 @@ async function generateMigrationsJsonAndUpdatePackageJson(
       excludeAppliedMigrations: opts.excludeAppliedMigrations,
     });
 
-    const { migrations, packageUpdates } = await migrator.migrate(
-      opts.targetPackage,
-      opts.targetVersion
-    );
+    const { migrations, packageUpdates, minVersionWithSkippedUpdates } =
+      await migrator.migrate(opts.targetPackage, opts.targetVersion);
 
     updatePackageJson(root, packageUpdates);
     await updateInstallationDetails(root, packageUpdates);
@@ -1264,7 +1276,15 @@ async function generateMigrationsJsonAndUpdatePackageJson(
         ...(migrations.length > 0
           ? [`- Run '${pmc.exec} nx migrate --run-migrations'`]
           : []),
-        `- To learn more go to https://nx.dev/core-features/automate-updating-dependencies`,
+        ...(opts.interactive && minVersionWithSkippedUpdates
+          ? [
+              `- You opted out of some migrations for now. Write the following command down somewhere to apply these migrations later:`,
+              `  nx migrate ${opts.targetVersion} --from ${opts.targetPackage}@${minVersionWithSkippedUpdates} --exclude-applied-migrations`,
+              `- To learn more go to https://nx.dev/recipes/other/advanced-update`,
+            ]
+          : [
+              `- To learn more go to https://nx.dev/core-features/automate-updating-dependencies`,
+            ]),
         ...(showConnectToCloudMessage()
           ? [
               `- You may run '${pmc.run(