Add detailed documentation for custom property editor migration to V14+

15/umbraco-cms/SUMMARY.md

@@ -27,6 +27,7 @@
     * [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 custom Property Editors to Umbraco 14+](fundamentals/setup/upgrading/version-specific/migrate-custom-property-editors-to-umbraco-14.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

@@ -185,7 +185,7 @@ For example, it is hardly a server concern how many rows a text area should span
 
 To this end, property editors have been split into two, individually reusable parts; the server implementation and the client implementation.
 
-As a consequence, a property editor must now define both which client and server implementation to use. Details can be found in [Creating a Property Editor](https://docs.umbraco.com/umbraco-cms/tutorials/creating-a-property-editor) article.
+This change will likely impact custom Property Editors. See the [Migrate custom Property Editors to Umbraco 14](./migrate-custom-property-editors-to-umbraco-14.md) article for details.
 
 * **Property value converters for package.manifest based property editors**
 
@@ -1062,7 +1062,7 @@ Remove `u.UseInstallerEndpoints();` from the `program.cs` file to avoid issues w
 
 **Update code using Angular JS**
 
-Angular JS has been removed in Umbraco 14. If you have extended your Umbraco project using Angular JS, it must be updated. for more information read the [Customize Backoffice](../../../../customizing/extend-and-customize-editing-experience.md) documentation.
+Angular JS has been removed in Umbraco 14. If you have extended your Umbraco project using Angular JS, it must be updated. for more information read the [Customize Backoffice](../../../../customizing/overview.md) documentation.
 
 **Deprecated property editors**
 
@@ -1401,7 +1401,7 @@ This is possible using Models Builder and through the inclusion of [core propert
 
 To not break everybody's sites (the results of queries are different when PVCs are enabled), we disabled these PVCs by default.
 
-Umbraco 7.6.0 also came with new pickers that store their data as a [UDI (Umbraco Identifier)](https://our.umbraco.com/Documentation/Reference/Querying/Udi). We wanted to simplify the use of these new pickers and by default we wanted PVC's to always be enabled for those pickers.
+Umbraco 7.6.0 also came with new pickers that store their data as a [UDI (Umbraco Identifier)](https://docs.umbraco.com/umbraco-cms/reference/querying/udi-identifiers). We wanted to simplify the use of these new pickers and by default we wanted PVC's to always be enabled for those pickers.
 
 We noticed that some new pickers also got their PVC's disabled when the configuration setting was set to false (`<EnablePropertyValueConverters>false</EnablePropertyValueConverters>`).
 
@@ -1552,7 +1552,7 @@ and
 
 Umbraco Forms 6.0.0 has been released to be compatible with Umbraco 7.6. It is a new major version release of Forms primarily due to the strict dependency on 7.6+. If you are using Forms, you will need to update it to version 6.0.0
 
-There are [**important Forms upgrade documentation that you will need to read.**](https://docs.umbraco.com/umbraco-forms/installation/version-specific.md#version-4-to-version-6).
+There are [**important Forms upgrade documentation that you will need to read.**](https://github.com/umbraco/UmbracoDocs/blob/umbraco-eol-versions/11/umbraco-forms/installation/version-specific.md).
 
 **Courier**
 

15/umbraco-cms/fundamentals/setup/upgrading/version-specific/migrate-custom-property-editors-to-umbraco-14.md

@@ -0,0 +1,126 @@
+---
+description: >-
+  This article will help you migrate custom Property Editors to Umbraco 14+
+---
+
+# Migrate custom Property Editors to Umbraco 14+
+
+{% hint style="info" %}
+This article _only_ applies to implementers of custom Property Editors - that is:
+
+- Maintainers of Property Editor packages.
+- Site implementers who have built their own Property Editors.
+{% endhint %}
+
+Umbraco 14 introduces a split between server-side and client-side Property Editor aliases. The reasoning behind this change is two-fold:
+
+1. It allows server-side implementations to be reused for multiple client-side Property Editor UIs.
+2. It helps to ensure a better division between client-side and server-side responsibility.
+
+## The migration impact for Property Editors
+
+In the Umbraco source code, the change manifests as the `EditorUiAlias` property on `IDataType`. 
+
+When upgrading from Umbraco 13 to Umbraco 14+, we migrate all Data Types to ensure an `EditorUiAlias` value. For custom Property Editors, this migration is based on certain assumptions.
+
+### Manifest based Property Editors
+
+If the Property Editor is built with a [package manifest](https://docs.umbraco.com/umbraco-cms/13.latest/tutorials/creating-a-property-editor#setting-up-a-plugin), we:
+
+1. Assign the package manifest `alias` to the Data Type `EditorUiAlias`, and
+2. Convert the Data Type `EditorAlias` to the alias of a core Data Editor, based on the `valueType` specified in the package manifest.
+
+The following table contains the applied conversion from `valueType` to `EditorAlias`
+
+| Property Editor `valueType` | Resulting `EditorAlias`  |
+|-----------------------------|--------------------------|
+| `BIGINT`                    | `Umbraco.Plain.Integer`  |
+| `DATE`                      | `Umbraco.Plain.DateTime` |
+| `DATETIME`                  | `Umbraco.Plain.DateTime` |
+| `DECIMAL`                   | `Umbraco.Plain.Decimal`  |
+| `JSON`                      | `Umbraco.Plain.Json`     |
+| `INT`                       | `Umbraco.Plain.Integer`  |
+| `STRING`                    | `Umbraco.Plain.String`   |
+| `TEXT`                      | `Umbraco.Plain.String`   |
+| `TIME`                      | `Umbraco.Plain.Time`     |
+| `XML`                       | `Umbraco.Plain.String`   |
+
+{% hint style="warning" %}
+**This might also impact Property Value Converters**
+
+Property Value Converters for package manifest based Property Editors might be impacted by this migration.
+
+It is common practice to pair a Property Editor to a Property Value Converter using the package manifest `alias`:
+
+```csharp
+public bool IsConverter(IPublishedPropertyType propertyType)
+  => propertyType.EditorAlias.Equals("My.Editor.Alias");
+```
+
+Since the migration moves the `alias` to `EditorUiAlias`, the Umbraco 14+ equivalent code looks like this:
+
+```csharp
+public bool IsConverter(IPublishedPropertyType propertyType)
+  => propertyType.EditorUiAlias.Equals("My.Editor.Alias");
+```
+{% endhint %}
+
+### Code based editors
+
+If the Property Editor is built with a [Data Editor](https://docs.umbraco.com/umbraco-cms/13.latest/tutorials/creating-a-property-editor#setting-up-a-property-editor-with-csharp), we:
+
+1. Assign the Data Editor `Alias` to the Data Type `EditorUiAlias`, and
+2. Retain the Data Type `EditorAlias` to as-is (which is the Data Editor `Alias`).
+
+{% hint style="info" %}
+The Data Editor `Alias` is found in the `DataEditor` attribute:
+
+```csharp
+[DataEditor("My.Editor.Alias")]
+public class MySuggestionsDataEditor : DataEditor
+{
+}
+```
+{% endhint %}
+
+## The migration impact for porting Property Editor UIs
+
+The [`umbraco-package.json`](https://docs.umbraco.com/umbraco-cms/tutorials/creating-a-property-editor#setting-up-a-plugin) file is a central component for extensions in Umbraco 14+, including Property Editor UIs.
+
+To keep the Property Editor working with migrated properties, ensure that the `propertyEditorUi` extension is declared with:
+
+1. The migrated value of `EditorUiAlias` as its `alias`, and
+2. The migrated value of `EditorAlias` as its `propertyEditorSchemaAlias` (found in the extension `meta` collection).
+
+For example:
+
+{% code title="umbraco-package.json" %}
+```json
+{
+    "name": "My.Editors",
+    "version": "1.0.0",
+    "extensions": [
+        {
+            "type": "propertyEditorUi",
+            "alias": "My.Editor.Alias",
+            (...)
+            "meta": {
+                "propertyEditorSchemaAlias": "Umbraco.Plain.String",
+                (...)
+            }
+        }
+    ]
+}
+```
+{% endcode %}
+
+{% hint style="info" %}
+See also the [Creating a Property Editor](https://docs.umbraco.com/umbraco-cms/tutorials/creating-a-property-editor) article for guidance on building a Property Editor UI for Umbraco 14+.
+{% endhint %}
+
+## Alternatives
+
+If the Data Type migration yields an undesirable result, your have two options:
+
+1. Manually change the `EditorAlias` and/or `EditorUiAlias` directly in the `umbracoDataType` table, or 
+2. Create a custom migration to update the properties (see [this article](https://docs.umbraco.com/umbraco-cms/extending/database) for inspiration).