Added details of breaking changes for 17

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

@@ -19,6 +19,167 @@ Use the [general upgrade guide](../) to complete the upgrade of your project.
 
 <details>
 
+<summary>Umbraco 17</summary>
+
+**System dates are updated to UTC**
+
+In earlier versions of Umbraco, system dates have been primarily persisted as server time without timezone information, with some stored as UTC. With Umbraco 17 we have rationalized this to always store UTC.
+
+To ensure that existing stored system dates align, a migration will run when upgrading to Umbraco 17.
+
+The migration consists of:
+- Determining the current timezone for the server.
+- If found and not already UTC, run database queries to update all the system dates that were previously stored in Umbraco as server time, to UTC.
+
+There is configuration available to customize this migration.
+
+Adding the following configuration setting will disable the migration from running.
+
+```json
+  "Umbraco": {
+    "CMS": {
+      "SystemDateMigration": {
+        "Enabled": false
+      }
+    }
+  }
+```
+
+You can also explicitly define the timezone for your server. If this is provided as the standard English name of the timezone, it will be used over the detected one.
+
+```json
+  "Umbraco": {
+    "CMS": {
+      "SystemDateMigration": {
+        "LocalServerTimeZone": "Eastern Standard Time"
+      }
+    }
+  }
+```
+
+Progress of the migration is written to the Umbraco log file.
+
+For more details on this update see the following PRs: [#19705](https://github.com/umbraco/Umbraco-CMS/pull/19705), [#19798](https://github.com/umbraco/Umbraco-CMS/pull/19798), and [#20112](https://github.com/umbraco/Umbraco-CMS/pull/20112).
+
+**InMemoryAuto models builder and razor runtime compilation has moved into its own package**
+
+InMemoryAuto models builder has been moved into a new package `Umbraco.Cms.DevelopmentMode.Backoffice` along with the reference to `Microsoft.AspNetCore.Mvc.Razor.RuntimeCompilation` and associated code.
+
+This change has been made due to the [obsoletion of Razor run-time compilation in .NET](https://learn.microsoft.com/en-us/dotnet/core/compatibility/aspnet-core/10/razor-runtime-compilation-obsolete). InMemoryAuto depends on Razor run-time compilation, and Razor run-time compilation is not compatible with hot reload. This means that as long as InMemoryAuto exists in the codebase, we cannot enable hot reload. To enable working towards hot reload being the default developer experience, we have moved InMemoryAuto into its own package.
+
+If you use InMemoryAuto models builder, or rely Razor runtime compilation in editing templates via the backoffice, you need to reference the `Umbraco.Cms.DevelopmentMode.Backoffice` package.
+
+If you use the RoslynCompiler class in Umbraco, you need to reference the `Umbraco.Cms.DevelopmentMode.Backoffice` package and update your namespace usings.
+
+If you use the `ModelsMode` enum or its extension methods, you instead need to use the strings in `Constants.ModelsBuilder.ModelsModes`.
+
+For new projects, this reference is added automatically if the `--models-mode`, is set to the default of InMemoryAuto, otherwise it won't.
+
+For more details on this update see the following PR: [#20187](https://github.com/umbraco/Umbraco-CMS/pull/20187).
+
+**Date Picker Property Editor Kind**
+
+The existing date picker that returns a `DateTime` object has been updated to provide one with a `Kind` of `Unspecified`. Previously it was `Utc` but this wasn't correct as Umbraco cannot what's intended by a particular usage of a date picker. This update makes that explicit.
+
+For more details on this update see the following PR: [#19727](https://github.com/umbraco/Umbraco-CMS/pull/19727).
+
+**Color Picker Property Editor**
+
+The color picker property editor used for the built-in approved color Data Type will now always make available a `PickedColor` object. Previously this was only output when labels were configured on the Data Type. Without labels the previous behavior was to expose a `string`.
+
+For more details on this update see the following PR: [#19430](https://github.com/umbraco/Umbraco-CMS/pull/19430).
+
+**Segmented Content Fallback**
+
+The template and delivery API output segmented properties will perform an explicit fallback to the default segment, if they do not have a value.
+
+In earlier versions, if you created a segmented version of a document, you had to complete every property. This made segments an editorial burden unless the behavior was customized. With the new behavior, segmented content only needs properties that need a segmented value need to be completed.
+
+For more details on this update see the following PR: [#20309](https://github.com/umbraco/Umbraco-CMS/pull/20309).
+
+**Removal of Extension Methods**
+
+Extension and public helper methods, unused in Umbraco and obsolete in previous versions, have been removed.
+
+These are:
+
+- `GetAssemblyFile`
+- `ToSingleItemCollection`
+- `GenerateDataTable`, `CreateTableData`, `AddRowData`, `ChildrenAsTable`, `ChildrenAsTable` all related to `DataTable`
+- `RetryUntilSuccessOrTimeout`
+- `RetryUntilSuccessOrMaxAttempts`
+- `HasFlagAny`
+- `Deconstruct`
+- `AsEnumerable`, `ContainsKey` and `GetValue` extending `NameValueCollection`
+- `DisposeIfDisposable`
+- `SafeCast`
+- `ToDictionary` on `object`
+- `SanitizeThreadCulture`
+
+For more details on this update see the following PR: [#17051](https://github.com/umbraco/Umbraco-CMS/pull/17051).
+
+**Tiptap external extensions package**
+
+The import namespace `@umbraco-cms/backoffice/external/tiptap` has been removed, replaced with `@umbraco-cms/backoffice/tiptap`.
+
+This means backoffice extension code would need to be updated from:
+
+```Typescript
+import { Editor } from '@umbraco-cms/backoffice/external/tiptap';
+```
+
+To:
+
+```Typescript
+import { Editor } from '@umbraco-cms/backoffice/tiptap';
+```
+
+For more details on this update see the following PR: [#20256](https://github.com/umbraco/Umbraco-CMS/pull/20256).
+
+**Client-side user related entities**
+
+The following components have been moved from `user` to `current-user` and exported.
+
+- `UmbCurrentUserAllowMfaActionCondition`
+- `UmbCurrentUserConfigRepository`
+- `UmbCurrentUserConfigStore`
+- `UMB_CURRENT_USER_CONFIG_STORE_CONTEXT`
+
+They should now be imported from `@umbraco-cms/backoffice/current-user`.
+
+For more details on this update see the following PR: [#20125](https://github.com/umbraco/Umbraco-CMS/pull/20125).
+
+**URL provider updates**
+
+URL providers are now responsible for generating content preview URLs. To achieve this, the `IUrlProvider` interface has been extended with the `GetPreviewUrlAsync()` method.
+
+The `IUrlProvider` interface must also provide a system-wide unique `Alias`.
+
+Lastly, the `UrlInfo` class has been revamped to support this setup.
+
+For more details on this update see the following PR: [#20021](https://github.com/umbraco/Umbraco-CMS/pull/20021).
+
+See also this announcement: [#27](https://github.com/umbraco/Announcements/issues/27).
+
+**Updated dependencies**
+
+As is usual for a major upgrade, the dependencies Umbraco takes have been updated to their latest, compatible versions.
+
+NPoco was updated by a major version from 5.7.1 to 6.1.0. There were some changes to Umbraco code necessary after this update, so customer projects or packages that use NPoco directly may also require some change.
+
+The other specific dependency updates made for Umbraco 17 for server and client-side libraries can be found in these PRs:
+
+- [#20385](https://github.com/umbraco/Umbraco-CMS/pull/20385)
+- [#20184](https://github.com/umbraco/Umbraco-CMS/pull/20184)
+
+**Other breaking changes**
+
+The full details of breaking changes can be found from [this list of labelled PRs](https://github.com/umbraco/Umbraco-CMS/pulls?q=is:pr+label:category/breaking+is:closed+label:release/17.0.0).
+
+</details>
+
+<details>
+
 <summary>Umbraco 16</summary>
 
 **TinyMCE is removed**
@@ -115,7 +276,7 @@ Below you can find the list of breaking changes introduced in Umbraco 14 CMS.
 
 * [**AngularJS removed: A new backoffice built with Web Components, Lit, and fueled by the Umbraco UI Library**](https://github.com/umbraco/Umbraco.CMS.Backoffice)
 
-This is by far the most impactful update of Umbraco in years. We’ve fundamentally changed the way you extend Umbraco. If you are experienced in developing Web Components you can now use your preferred framework for this. If you are unsure how to proceed, you can implement it with Typescript and the Lit library like we’ve done. In this case, please start with this article on how to [customize the Backoffice](https://docs.umbraco.com/umbraco-cms/customizing/overview).
+This is by far the most impactful update of Umbraco in years. We’ve fundamentally changed the way you extend Umbraco. If you are experienced in developing Web Components you can now use your preferred framework for this. If you are unsure how to proceed, you can implement it with TypeScript and the Lit library like we’ve done. In this case, please start with this article on how to [customize the Backoffice](https://docs.umbraco.com/umbraco-cms/customizing/overview).
 
 The new Backoffice (Bellissima) is entirely built on the Umbraco UI Library. This means that you might experience some of your components not being rendered on the page because the name has been changed. You should be able to find equivalents to what you were used to. For example, the `umb-button` is now called `uui-button`, and `umb-box` is now `uui-box`. When extending the Backoffice, we encourage you to use our [Umbraco UI Library](https://uui.umbraco.com/) to ensure the same look and feel in your extensions. The UI Library is Open Source and [hosted on GitHub](https://github.com/umbraco/Umbraco.UI), so feel free to contribute with new components or raise issues or discussions.