Merge pull request #2242 from unoplatform/dev/sb/itemspanel-markup

docs: add upgrading docs and itemspanel breaking changes

doc/Learn/Markup/Overview.md

@@ -192,3 +192,4 @@ Learn more about:
 - [VisualStateManagers](xref:Uno.Extensions.Markup.VisualStateManager)
   - [Storyboards](xref:Uno.Extensions.Markup.Storyboards)
 - [Generating C# Extensions for your libraries](xref:Uno.Extensions.Markup.GeneratingExtensions)
+- [Upgrading C# Markup](xref:Uno.Extensions.Markup.Upgrading)

doc/Learn/Markup/Templates.md

@@ -49,16 +49,19 @@ new Button()
             .Content(x => x.TemplateBind(() => button.Content))))
 ```
 
-## All other Framework Templates
+## ItemsPanelTemplate
 
-In all other cases, `Template` properties are treated the same with a simple delegate expected to return the desired UI. In these cases, it is assumed that the same context as the parent is available and there is no need for additional typing on the delegate.
+An `ItemsPanelTemplate` should contain exactly one `FrameworkElement`-derived class that serves as the root element for items. As a result, `ItemsPanelTemplate` properties are built using a strongly typed generic extension that will give you access to a `configureItemsPanel` delegate that will allow you to configure the element used as the root of the `ItemsPanelTemplate` with the desired properties.
 
 ```cs
 new ListView()
-    .ItemsPanel(() => new ItemsStackPanel()
-        .Orientation(Orientation.Vertical))
+    .ItemsPanel<ItemsStackPanel>(panel => panel.Orientation(Orientation.Vertical))
 ```
 
+## All other Framework Templates
+
+In all other cases, `Template` properties are treated the same with a simple delegate expected to return the desired UI. In these cases, it is assumed that the same context as the parent is available and there is no need for additional typing on the delegate.
+
 ## Next Steps
 
 Learn more about:

doc/Learn/Markup/Upgrading.md

@@ -0,0 +1,28 @@
+---
+uid: Uno.Extensions.Markup.Upgrading
+---
+
+# Upgrading C# Markup
+
+## Changes in v5.2
+
+### ItemsPanel Property
+
+The signature for the `ItemsPanel` property extension method has changed to a strongly typed generic method that accepts a delegate to configure the root element of the `ItemsPanelTemplate`. 
+
+The `ItemsPanel` property extension method that previously looked like this:
+
+```cs
+new ListView()
+    .ItemsPanel(() => new ItemsStackPanel()
+        .Orientation(Orientation.Vertical))
+```
+
+Should now be updated to:
+
+```cs
+new ListView()
+    .ItemsPanel<ItemsStackPanel>(panel => panel.Orientation(Orientation.Vertical))
+```
+
+To learn more about different types of templates in C# Markup, see the [Templates section](xref:Uno.Extensions.Markup.Templates).

doc/Learn/Markup/toc.yml

@@ -2,6 +2,8 @@
 
 - name: Overview
   href: xref:Uno.Extensions.Markup.Overview
+- name: Upgrading
+  href: xref:Uno.Extensions.Markup.Upgrading
 - name: Binding, Static & Theme Resources
   href: xref:Uno.Extensions.Markup.DependencyPropertyBuilder
   items: