From ee7a95d8f6c3574b007721915df3a1aabcad9428 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Leosvel=20P=C3=A9rez=20Espinosa?= Date: Wed, 10 May 2023 08:32:42 +0100 Subject: [PATCH] feat(core): log a note after an interactive migration run with skipped package updates --- .../automate-updating-dependencies.md | 6 ++-- docs/shared/recipes/advanced-update.md | 33 ++++++++++++++++++- .../src/command-line/migrate/migrate.spec.ts | 10 ++++++ .../nx/src/command-line/migrate/migrate.ts | 32 ++++++++++++++---- 4 files changed, 71 insertions(+), 10 deletions(-) diff --git a/docs/shared/core-features/automate-updating-dependencies.md b/docs/shared/core-features/automate-updating-dependencies.md index 1158778d91fb99..07a5f3f5eb21fa 100644 --- a/docs/shared/core-features/automate-updating-dependencies.md +++ b/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. diff --git a/docs/shared/recipes/advanced-update.md b/docs/shared/recipes/advanced-update.md index 5017f627ba9cff..edb92b99fc5388 100644 --- a/docs/shared/recipes/advanced-update.md +++ b/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 diff --git a/packages/nx/src/command-line/migrate/migrate.spec.ts b/packages/nx/src/command-line/migrate/migrate.spec.ts index 9985b0102c848d..0407f27ae2ee24 100644 --- a/packages/nx/src/command-line/migrate/migrate.spec.ts +++ b/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(); }); diff --git a/packages/nx/src/command-line/migrate/migrate.ts b/packages/nx/src/command-line/migrate/migrate.ts index 5942e928bc6aa4..3bf055aff782d7 100644 --- a/packages/nx/src/command-line/migrate/migrate.ts +++ b/packages/nx/src/command-line/migrate/migrate.ts @@ -137,6 +137,7 @@ export class Migrator { private readonly collectedVersions: Record = {}; private readonly promptAnswers: Record = {}; 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(