refactor(@angular/cli): show optional migration name and documentatio…

…n URL if available during updates

The optional migration selection prompt shown during an interactive
`ng update` will now show the name of the migration which can be used
to manually run the update at a later time as well as a documentation link
if present for the migration.

packages/angular/cli/src/commands/update/cli.ts

@@ -67,6 +67,7 @@ interface MigrationSchematicDescription
   extends SchematicDescription<FileSystemCollectionDescription, FileSystemSchematicDescription> {
   version?: string;
   optional?: boolean;
+  documentation?: string;
 }
 
 interface MigrationSchematicDescriptionWithVersion extends MigrationSchematicDescription {
@@ -1082,10 +1083,6 @@ export default class UpdateCommandModule extends CommandModule<UpdateCommandArgs
         numberOfMigrations > 1 ? 's' : ''
       } that can be executed.`,
     );
-    logger.info(
-      'Optional migrations may be skipped and executed after the update process if preferred.',
-    );
-    logger.info(''); // Extra trailing newline.
 
     if (!isTTY()) {
       for (const migration of optionalMigrations) {
@@ -1098,13 +1095,18 @@ export default class UpdateCommandModule extends CommandModule<UpdateCommandArgs
       return undefined;
     }
 
+    logger.info(
+      'Optional migrations may be skipped and executed after the update process, if preferred.',
+    );
+    logger.info(''); // Extra trailing newline.
+
     const answer = await askChoices(
       `Select the migrations that you'd like to run`,
       optionalMigrations.map((migration) => {
-        const { title } = getMigrationTitleAndDescription(migration);
+        const { title, documentation } = getMigrationTitleAndDescription(migration);
 
         return {
-          name: title,
+          name: `[${colors.white(migration.name)}] ${title}${documentation ? ` (${documentation})` : ''}`,
           value: migration.name,
         };
       }),
@@ -1182,11 +1184,15 @@ function coerceVersionNumber(version: string | undefined): string | undefined {
 function getMigrationTitleAndDescription(migration: MigrationSchematicDescription): {
   title: string;
   description: string;
+  documentation?: string;
 } {
   const [title, ...description] = migration.description.split('. ');
 
   return {
     title: title.endsWith('.') ? title : title + '.',
     description: description.join('.\n  '),
+    documentation: migration.documentation
+      ? new URL(migration.documentation, 'https://angular.dev').href
+      : undefined,
   };
 }

packages/schematics/angular/migrations/migration-collection.json

@@ -4,7 +4,8 @@
       "version": "18.0.0",
       "factory": "./use-application-builder/migration",
       "description": "Migrate application projects to the new build system. Application projects that are using the '@angular-devkit/build-angular' package's 'browser' and/or 'browser-esbuild' builders will be migrated to use the new 'application' builder. You can read more about this, including known issues and limitations, here: https://angular.dev/tools/cli/build-system-migration",
-      "optional": true
+      "optional": true,
+      "documentation": "tools/cli/build-system-migration"
     }
   }
 }