Repository: umbraco/UmbracoDocs
Pull request #7038: Updates relating to 16.0.0-rc
Author: login: AndyButland
Labels: name: category/umbraco-cms
name: release/16.0.0
Created: 2025-04-23T08:04:51Z | Merged: 2025-04-29T14:48:39Z

## Description

Includes the following:

- Version specific upgrade guide breaking changes.
- Details of additional logging settings provided via https://github.com/umbraco/Umbraco-CMS/pull/19074
- Details of asynchronous package migrations provided via https://github.com/umbraco/Umbraco-CMS/pull/17057

## Type of suggestion

* [ ] Typo/grammar fix
* [ ] Updated outdated content
* [ ] New content
* [X] Updates related to a new version
* [ ] Other

## Product & version (if relevant)

Umbraco CMS 16.0.0-rc

## Deadline (if relevant)

We should publish this when the RC is released.  For now, keeping in draft.



Diff:
diff --git a/16/umbraco-cms/extending/packages/creating-a-package.md b/16/umbraco-cms/extending/packages/creating-a-package.md
index c11745c70ac..6f3e5a0d1ee 100644
--- a/16/umbraco-cms/extending/packages/creating-a-package.md
+++ b/16/umbraco-cms/extending/packages/creating-a-package.md
@@ -124,7 +124,7 @@ You can specify package metadata directly in the `csproj` file. Here, is an exam
 ```xml
 <Project Sdk="Microsoft.NET.Sdk">
     <PropertyGroup>
-        . . . 
+        . . .
         <Title>CustomWelcomeDashboard</Title>
         <Description>Custom welcome dashboard for Umbraco.</Description>
         <PackageTags>umbraco plugin package</PackageTags>
@@ -282,7 +282,7 @@ public class CustomPackageMigration : PackageMigrationBase
         IShortStringHelper shortStringHelper,
         IContentTypeBaseServiceProvider contentTypeBaseServiceProvider,
         IMigrationContext context,
-        IOptions<PackageMigrationSettings> packageMigrationsSettings) 
+        IOptions<PackageMigrationSettings> packageMigrationsSettings)
         : base(
             packagingService,
             mediaService,
@@ -302,6 +302,54 @@ public class CustomPackageMigration : PackageMigrationBase
 }
 ```
 
+If your migration step has a requirement for asynchronous work, you can also inherit from `AsyncPackageMigrationBase`:
+
+```csharp
+using Microsoft.Extensions.Options;
+using Umbraco.Cms.Core.Configuration.Models;
+using Umbraco.Cms.Core.IO;
+using Umbraco.Cms.Core.Models.Membership;
+using Umbraco.Cms.Core.PropertyEditors;
+using Umbraco.Cms.Core.Services;
+using Umbraco.Cms.Core.Strings;
+using Umbraco.Cms.Infrastructure.Migrations;
+using Umbraco.Cms.Infrastructure.Packaging;
+
+namespace Umbraco.Cms.Web.UI.Custom.PackageMigration;
+
+public class CustomPackageAsyncMigration : AsyncPackageMigrationBase
+{
+
+    public TestMigrationStep2(
+        IPackagingService packagingService,
+        IMediaService mediaService,
+        MediaFileManager mediaFileManager,
+        MediaUrlGeneratorCollection mediaUrlGenerators,
+        IShortStringHelper shortStringHelper,
+        IContentTypeBaseServiceProvider contentTypeBaseServiceProvider,
+        IMigrationContext context,
+        IOptions<PackageMigrationSettings> packageMigrationsSettings,
+        IUserGroupService userGroupService,
+        IUserService userService)
+        : base(
+              packagingService,
+              mediaService,
+              mediaFileManager,
+              mediaUrlGenerators,
+              shortStringHelper,
+              contentTypeBaseServiceProvider,
+              context,
+              packageMigrationsSettings)
+    {
+    }
+
+    protected override async Task MigrateAsync()
+    {
+        // Use await for asynchronous work.
+    }
+}
+```
+
 Here we also added the ZIP file as an embedded resource to the package project.
 
 ![ZIP as an embedded resource](<../../../../10/umbraco-cms/extending/packages/images/embeded-resource-props (1).png>)
diff --git a/16/umbraco-cms/fundamentals/setup/upgrading/version-specific/README.md b/16/umbraco-cms/fundamentals/setup/upgrading/version-specific/README.md
index e0d59217ade..a973e25fbdb 100644
--- a/16/umbraco-cms/fundamentals/setup/upgrading/version-specific/README.md
+++ b/16/umbraco-cms/fundamentals/setup/upgrading/version-specific/README.md
@@ -19,6 +19,22 @@ Use the [general upgrade guide](../) to complete the upgrade of your project.
 
 <details>
 
+<summary>Umbraco 16</summary>
+
+**TinyMCE is removed**
+
+In Umbraco 15, two property editors were available for a rich text editor: TinyMCE and TipTap.
+
+With Umbraco 16, only TipTap is available as an option out of the box. TinyMCE's [change of license](https://github.com/tinymce/tinymce/issues/9453#issuecomment-2327646149) precludes us from shipping it with the MIT-licensed Umbraco CMS.
+
+When upgrading to Umbraco 16, any data types using TinyMCE will be migrated to use TipTap.
+
+To continue to use TinyMCE, a third-party package must be installed prior to the upgrade. This will disable the migration and allow you to continue with TinyMCE.
+
+</details>
+
+<details>
+
 <summary>Umbraco 15</summary>
 
 **Snapshots are removed**
diff --git a/16/umbraco-cms/reference/configuration/loggingsettings.md b/16/umbraco-cms/reference/configuration/loggingsettings.md
index 5a4eb24d4cf..f3357d30fb9 100644
--- a/16/umbraco-cms/reference/configuration/loggingsettings.md
+++ b/16/umbraco-cms/reference/configuration/loggingsettings.md
@@ -13,7 +13,9 @@ The following configuration is available in the Logging settings:
   "CMS": {
     "Logging": {
       "MaxLogAge": "2.00:00:00",
-      "Directory": "~/CustomLogFileLocation"
+      "Directory": "~/CustomLogFileLocation",
+      "FileNameFormat": "UmbracoTraceLog.{0}..json",
+      "FileNameFormatArguments": "MachineName"
     }
   }
 }
@@ -30,3 +32,22 @@ To increase the maximum age of the entries in the audit log to 48 hours (2 days)
 By default, all log files are saved to the `umbraco/Logs` directory. You can define a custom directory for your log files by using the `Directory` key in the Logging settings.
 
 Set the value to `~/LogFiles` to add all log files to a `LogFiles` directory in the root of the file structure.
+
+## FileNameFormat
+
+The default file name format for the Umbraco log file is `UmbracoTraceLog.{0}..json`. The single argument is replaced at runtime with the server's machine name.
+
+If you want to change the file name or include additional arguments, you can amend the format with the `FileNameFormat` setting.
+
+## FileNameFormatArguments
+
+By default the single argument for the log file format name is the server's machine name.
+
+Other or additional arguments can be provided via the `FileNameFormatArguments` setting using a comma-delimited string:
+
+- `MachineName` - the server's name.
+- `EnvironmentName` - the ASP.NET environment name such as "Development" or "Production.
+
+So for example, to provide both supported arguments you would configure `MachineName,EnvironmentName`.
+
+The number of arguments provided should match the placeholders in the configured `FileNameFormat`.


Reviews:
user: login: sofietoft
body: I know this is still in draft mode, but since the RC is going on tomorrow, I thought it made sense to start the review 😅 

In addition, I have a question:
Should we remove the breaking changes for the previous versions?
Or perhaps only keep the supported versions there? 🤔 So, that would be 10, 13 and 15 in this case..
This goes for both breaking changes and version specific upgrade notes.
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-29T09:16:16Z

Review comments:
diff_hunk: @@ -30,3 +32,22 @@ To increase the maximum age of the entries in the audit log to 48 hours (2 days)
 By default, all log files are saved to the `umbraco/Logs` directory. You can define a custom directory for your log files by using the `Directory` key in the Logging settings.
 
 Set the value to `~/LogFiles` to add all log files to a `LogFiles` directory in the root of the file structure.
+
+## FileNameFormat
+
+The default file name format for the Umbraco log file is `UmbracoTraceLog.{0}..json`. The single argument is replaced at runtime with the server's machine name.
+
+If you want to change the file name or include additional arguments, you can amend the format with this setting.
path: 16/umbraco-cms/reference/configuration/loggingsettings.md
user: login: sofietoft
body: ```suggestion
If you want to change the file name or include additional arguments, you can amend the format with the `FileNameFormat` setting.
```
created_at: 2025-04-29T09:13:23Z
author_association: CONTRIBUTOR
diff_hunk: @@ -30,3 +32,22 @@ To increase the maximum age of the entries in the audit log to 48 hours (2 days)
 By default, all log files are saved to the `umbraco/Logs` directory. You can define a custom directory for your log files by using the `Directory` key in the Logging settings.
 
 Set the value to `~/LogFiles` to add all log files to a `LogFiles` directory in the root of the file structure.
+
+## FileNameFormat
+
+The default file name format for the Umbraco log file is `UmbracoTraceLog.{0}..json`. The single argument is replaced at runtime with the server's machine name.
+
+If you want to change the file name or include additional arguments, you can amend the format with this setting.
+
+## FileNameFormatArguments
+
+By default the single argument for the log file format name is the server's machine name.
+
+Other or additional arguments can be provided via this setting as a comma delimited string:
path: 16/umbraco-cms/reference/configuration/loggingsettings.md
user: login: sofietoft
body: ```suggestion
Other or additional arguments can be provided via the `FileNameFormatArguments` setting using a comma-delimited string:
```
created_at: 2025-04-29T09:14:11Z
author_association: CONTRIBUTOR

PR comments:
user: login: sofietoft
created_at: 2025-04-23T09:04:03Z
body: Hi @AndyButland !

Will this include all Docs updates for Umbraco 16?

Also, the 16 docs is not published yet, and won't be until we publish the RC docs.
So, this can easily be merged before, as it will only be available here on GitHub until the RC release.

author_association: CONTRIBUTOR
user: login: AndyButland
created_at: 2025-04-23T09:55:30Z
body: I've suggested to the team they can add small things here - little updates as and where needed, like the one I've added.  Though likely anything more substantial will have their own PRs to make them easier to review.
author_association: CONTRIBUTOR
user: login: sofietoft
created_at: 2025-04-23T10:31:13Z
body: Great! I see we have a meeting tomorrow, so we should coordinate who writes what - just so we don't accidentally do double-work.
author_association: CONTRIBUTOR
user: login: AndyButland
created_at: 2025-04-29T11:05:45Z
body: Good point @sofietoft!  Thanks, and sorry for forgetting to mark this as ready for review.

On the breaking changes point, I think it's probably best to keep in actually.  Just as if you are going from say 13 to 16, it makes sense you read the breaking changes between 13 to 14 and 14 to 15, even if you are upgrading in one step.  You could go and find the 14 and 15 docs to see these, but it's an extra step and it may not be obvious that you should review them.
author_association: CONTRIBUTOR
user: login: sofietoft
created_at: 2025-04-29T12:29:51Z
body: Yes, good points about the breaking changes docs 🤔 
We could remove the RC and Beta ones for 14 though, right?
![image](https://github.com/user-attachments/assets/bb4fb58b-1569-4986-bb38-3527bbc93db4)

And perhaps 12 and 11, as they are no longer supported, so you wouldn't be updated to those - and I don't believe you even need to, in order to go from 10 to 13 🤔 
author_association: CONTRIBUTOR
user: login: AndyButland
created_at: 2025-04-29T12:54:34Z
body: The beta and RC ones could go for non-current versions I'm sure.

But for this...

> And perhaps 12 and 11, as they are no longer supported, so you wouldn't be updated to those - and I don't believe you even need to, in order to go from 10 to 13

... I think we should keep.  You are right that you don't need to do the intermediate upgrade steps - i.e. you can upgrade 10 to 13 - but you still might want to know what all the breaking changes are between the versions you are going between.
author_association: CONTRIBUTOR
user: login: sofietoft
created_at: 2025-04-29T14:48:15Z
body: Yes, you are right. The breaking changes remain relevant, so we'll keep them 😄 
Just thought it'd be a good opportunity to clean up a bit.

I'll merge this, and make sure the RC docs are published tomorrow.
author_association: CONTRIBUTOR