From cb385d25b7d01df537e5033e2f50bc585d9f15b8 Mon Sep 17 00:00:00 2001 From: kjac Date: Wed, 13 Nov 2024 11:29:16 +0100 Subject: [PATCH 1/3] Added docs for V15 content migration --- 15/umbraco-cms/SUMMARY.md | 1 + .../upgrading/version-specific/README.md | 8 +++ .../migrate-content-to-umbraco-15.md | 66 +++++++++++++++++++ 3 files changed, 75 insertions(+) create mode 100644 15/umbraco-cms/fundamentals/setup/upgrading/version-specific/migrate-content-to-umbraco-15.md diff --git a/15/umbraco-cms/SUMMARY.md b/15/umbraco-cms/SUMMARY.md index e3af8286c61..b49513edbc8 100644 --- a/15/umbraco-cms/SUMMARY.md +++ b/15/umbraco-cms/SUMMARY.md @@ -21,6 +21,7 @@ * [Upgrade your project](fundamentals/setup/upgrading/README.md) * [Version Specific Upgrades](fundamentals/setup/upgrading/version-specific/README.md) * [Upgrade from Umbraco 8 to the latest version](fundamentals/setup/upgrading/version-specific/upgrade-from-8-to-latest.md) + * [Migrate content to Umbraco 15](fundamentals/setup/upgrading/version-specific/migrate-content-to-umbraco-15.md) * [Migrate content to Umbraco 8](fundamentals/setup/upgrading/version-specific/migrate-content-to-umbraco-8.md) * [Minor upgrades for Umbraco 8](fundamentals/setup/upgrading/version-specific/minor-upgrades-for-umbraco-8.md) * [Upgrade to Umbraco 7](fundamentals/setup/upgrading/version-specific/upgrade-to-umbraco-7.md) diff --git a/15/umbraco-cms/fundamentals/setup/upgrading/version-specific/README.md b/15/umbraco-cms/fundamentals/setup/upgrading/version-specific/README.md index 1b00841cce7..e66effe6766 100644 --- a/15/umbraco-cms/fundamentals/setup/upgrading/version-specific/README.md +++ b/15/umbraco-cms/fundamentals/setup/upgrading/version-specific/README.md @@ -1069,6 +1069,14 @@ Macros and partial views macros have been removed in Umbraco 14. We recommend us For more information on what has changed in Umbraco 14 read the [Breaking changes in Umbraco 14](./#umbraco-14). +**Block Editor data format has changes** + +In Umbraco 15, the internal data format for [Block Editors](../../../../fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/block-editor/README.md) has changed. This causes a content migration to run when upgrading. + +This content migration can take a while to complete on a large site, causing it to be unresponsive for the duration. To speed up the migration, it is advised to [clean up old content versions](../../../../fundamentals/data/content-version-cleanup.md) before upgrading. + +While we don't recommend this, it might be possible for you to skip the content migration. More details can be found in the [Migrate content to Umbraco 15](migrate-content-to-umbraco-15.md) article. +
diff --git a/15/umbraco-cms/fundamentals/setup/upgrading/version-specific/migrate-content-to-umbraco-15.md b/15/umbraco-cms/fundamentals/setup/upgrading/version-specific/migrate-content-to-umbraco-15.md new file mode 100644 index 00000000000..89424bb6e10 --- /dev/null +++ b/15/umbraco-cms/fundamentals/setup/upgrading/version-specific/migrate-content-to-umbraco-15.md @@ -0,0 +1,66 @@ +--- +description: >- + This article will help you migrate content to Umbraco 15, and outline options to skip this content migration. +--- + +# Migrate content to Umbraco 15 + +Umbraco 15 changes the internal data format of all [Block Editors](../../../../fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/block-editor/README.md). + +If your maintain a large Umbraco site with extensive Block Editor usage, the upgrade to Umbraco 15+ might require a long-running content migration. For the duration of the migration, your site will be unresponsive and unable to serve requests. + +You can track the progress of the migration in the logs. + +It is advised to [clean up old content versions](../../../../fundamentals/data/content-version-cleanup.md) before upgrading. This will make the migration run faster. + +## Opting out of the content migration + +It is strongly recommended to let the migration run as part of the upgrade. However, if you are upgrading to Umbraco versions 15, 16 or 17, you _can_ opt out of the migration. Your site will continue to work, albeit with a certain degree of performance degradation. + +{% hint style="warning" %} +Blocks in Rich Text Editors might not work as expected if you opt out of the content migration. +{% endhint %} + +You can opt out of migrating each Block Editor type individually. To opt out, add an `IComposer` implementation to configure the `ConvertBlockEditorPropertiesOptions` before initiating the upgrade process: + +{% code title="DisableBlockEditorMigrationComposer.cs" %} + +```csharp +using Umbraco.Cms.Core.Composing; +using Umbraco.Cms.Infrastructure.Migrations.Upgrade.V_15_0_0; + +namespace UmbracoDocs.Samples; + +public class DisableBlockEditorMigrationComposer : IComposer +{ + [Obsolete] + public void Compose(IUmbracoBuilder builder) + => builder.Services.Configure(options => + { + // setting this to true will skip the migration of all Block List properties + options.SkipBlockListEditors = false; + + // setting this to true will skip the migration of all Block Grid properties + options.SkipBlockGridEditors = false; + + // setting this to true will skip the migration of all Rich Text Editor properties + options.SkipRichTextEditors = false; + }); +} +``` + +{% endcode %} + +Subsequently, you are responsible for performing the content migration yourself. This _must_ be done before upgrading past Umbraco 17. + +Custom code is required to perform the content migration. You can find inspiration in the core migrations: + +- [`ConvertBlockListEditorProperties`](https://github.com/umbraco/Umbraco-CMS/blob/contrib/src/Umbraco.Infrastructure/Migrations/Upgrade/V_15_0_0/ConvertBlockListEditorProperties.cs) for Block List properties. +- [`ConvertBlockGridEditorProperties`](https://github.com/umbraco/Umbraco-CMS/blob/contrib/src/Umbraco.Infrastructure/Migrations/Upgrade/V_15_0_0/ConvertBlockGridEditorProperties.cs) for Block Grid properties. +- [`ConvertRichTextEditorProperties`](https://github.com/umbraco/Umbraco-CMS/blob/contrib/src/Umbraco.Infrastructure/Migrations/Upgrade/V_15_0_0/ConvertRichTextEditorProperties.cs) for Rich Text Editor properties. + +{% hint style="warning" %} +This custom code should not run while editors are working in the Umbraco backoffice. + +Once the content migration is complete. the site may require a restart. +{% endhint %} From ebd85b90311adf6034208f1d7958c85df4c6b4e6 Mon Sep 17 00:00:00 2001 From: kjac Date: Wed, 13 Nov 2024 11:36:08 +0100 Subject: [PATCH 2/3] Make the linter happy --- .../upgrading/version-specific/migrate-content-to-umbraco-15.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/15/umbraco-cms/fundamentals/setup/upgrading/version-specific/migrate-content-to-umbraco-15.md b/15/umbraco-cms/fundamentals/setup/upgrading/version-specific/migrate-content-to-umbraco-15.md index 89424bb6e10..2876a8882e0 100644 --- a/15/umbraco-cms/fundamentals/setup/upgrading/version-specific/migrate-content-to-umbraco-15.md +++ b/15/umbraco-cms/fundamentals/setup/upgrading/version-specific/migrate-content-to-umbraco-15.md @@ -1,6 +1,6 @@ --- description: >- - This article will help you migrate content to Umbraco 15, and outline options to skip this content migration. + This article will help you migrate content to Umbraco 15, and outline options to skip this content migration --- # Migrate content to Umbraco 15 From 56754ebb8c45ec4f6617a8524096004f474ca8f5 Mon Sep 17 00:00:00 2001 From: sofietoft Date: Wed, 13 Nov 2024 13:00:53 +0100 Subject: [PATCH 3/3] Tiny fixes --- .../version-specific/migrate-content-to-umbraco-15.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/15/umbraco-cms/fundamentals/setup/upgrading/version-specific/migrate-content-to-umbraco-15.md b/15/umbraco-cms/fundamentals/setup/upgrading/version-specific/migrate-content-to-umbraco-15.md index 2876a8882e0..2b03fbc5e2b 100644 --- a/15/umbraco-cms/fundamentals/setup/upgrading/version-specific/migrate-content-to-umbraco-15.md +++ b/15/umbraco-cms/fundamentals/setup/upgrading/version-specific/migrate-content-to-umbraco-15.md @@ -7,7 +7,7 @@ description: >- Umbraco 15 changes the internal data format of all [Block Editors](../../../../fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/block-editor/README.md). -If your maintain a large Umbraco site with extensive Block Editor usage, the upgrade to Umbraco 15+ might require a long-running content migration. For the duration of the migration, your site will be unresponsive and unable to serve requests. +If you maintain a large Umbraco site with extensive Block Editor usage, the upgrade to Umbraco 15+ might require a long-running content migration. For the duration of the migration, your site will be unresponsive and unable to serve requests. You can track the progress of the migration in the logs. @@ -15,13 +15,13 @@ It is advised to [clean up old content versions](../../../../fundamentals/data/c ## Opting out of the content migration -It is strongly recommended to let the migration run as part of the upgrade. However, if you are upgrading to Umbraco versions 15, 16 or 17, you _can_ opt out of the migration. Your site will continue to work, albeit with a certain degree of performance degradation. +It is strongly recommended to let the migration run as part of the upgrade. However, if you are upgrading to Umbraco versions 15, 16, or 17, you _can_ opt out of the migration. Your site will continue to work, albeit with a certain degree of performance degradation. {% hint style="warning" %} Blocks in Rich Text Editors might not work as expected if you opt out of the content migration. {% endhint %} -You can opt out of migrating each Block Editor type individually. To opt out, add an `IComposer` implementation to configure the `ConvertBlockEditorPropertiesOptions` before initiating the upgrade process: +You can opt out of migrating each Block Editor type individually. To opt-out, add an `IComposer` implementation to configure the `ConvertBlockEditorPropertiesOptions` before initiating the upgrade process: {% code title="DisableBlockEditorMigrationComposer.cs" %} @@ -62,5 +62,5 @@ Custom code is required to perform the content migration. You can find inspirati {% hint style="warning" %} This custom code should not run while editors are working in the Umbraco backoffice. -Once the content migration is complete. the site may require a restart. +The site may require a restart once the content migration is complete. {% endhint %}