Documentation: Add Style Migration Guides

[michael-hawker]

The 2.4 WinUI update changed the NavigationView's style template (as has been done numerous times in the past as well). This makes it hard for developers who re-style controls to upgrade to the new library, especially when it's a minor version update (for instance the Windows Community Toolkit reserves breaking style changes for major version updates).

Even then, it'd be great to see a document/guideline that can walk a developer through updating a style targeting the previous version of the control to the updated version of the style. i.e. calling out things that have been removed or renamed or large structural changes between the styles.

Thanks!

[ranjeshj]

Re-templating a control is essentially forking the code. We need an equivalent of merging in the changes made in the framework to your own app where the template was copied.

If there are ways we can expose the customization points through the control, then we can avoid re-templating in most cases and mitigate this issue a bit.

Both the old style and the new styles are open, so is this specific ask to document them side by side ?

[michael-hawker]

@ranjeshj, yeah there's a few parts:

1. Calling out the policy that you don't consider style updates breaking changes for minor releases (as that seems a bit unusual).
2. Documenting breaking changes to styles as part of releases notes (e.g. the controls which styles have significantly changed and wouldn't be compatible with a style based off the previous version)
3. MVP Have documents linked from the release notes for each non-compatible style to a guide which explains the main changes to the style (node name changes, type changes, new/removed resource names, etc...)

And yes, I agree with more configuration points and things like #279 it'd make it easier to not have to fork the entire styles to do some customizations. However, depending on how deep those types of customizations can reach into the structure of a style, some similar issues may exist where this type of guide could be handy. It may just become simpler to recommend how to update an overwritten style in a 'light-weight form' compared to an entire copy like we do today.

Thanks!

[mdtauk]

This could be solved by including more detailed change logs for control changed

[michael-hawker]

Not the same request, but related for just documentation on styles in general: MicrosoftDocs/windows-dev-docs#1870