Merge pull request #6662 from kjac/v15/feature/migrate-content-for-V15

Added docs for V15 content migration

Author: sofietoft

15/umbraco-cms/SUMMARY.md

@@ -26,6 +26,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)

15/umbraco-cms/fundamentals/setup/upgrading/version-specific/README.md

@@ -1062,6 +1062,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.
+
 </details>
 
 <details>

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 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.
+
+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<ConvertBlockEditorPropertiesOptions>(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.
+
+The site may require a restart once the content migration is complete.
+{% endhint %}