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

…d package updates

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 in order to apply the migrations that were generated in `migrations.json` in the previous step. You can do so by running:
+
+```shell
+nx migrate --run-migrations
+```
+
+This will update your source code in your workspace in accordance with the implementation of the various migrations which ran and all the changes will be unstaged 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(