8.0 Release Plan 📝

[michael-hawker]

Latest info on Pre-release blog here https://devblogs.microsoft.com/ifdef-windows/windows-community-toolkit-8-0-pre-release/

Read more about our whole 2022 Release Plan summary on the discussion here.

Before we start looking at our full 8.0 release, we're re-working our infrastructure for the toolkit. Read all about the new Toolkit Labs for Windows coming first here.

H1 2023 - 8.0 Release – Create/Rename Windows Community Toolkit Repo to CommunityToolkit/Windows

• Leverage new tooling/improvements for project structure/samples/documentation/testing from Toolkit Labs for Windows.
• Maintain a single branch for all platform targets (e.g. UWP and WinUI 3)
• Ship all targeted platforms in a single NuGet package and namespace under CommunityToolkit.WinUI.*
  • Simplifies documentation and samples across platforms
  • Enables library and app developers to multi-target platforms and share XAML
  • Aids in transitions from UWP to WinUI 3 in the long-term.
• Seeded with code from our existing winui branch.
• Rename or Archive existing CommunityToolkit/WindowsCommunityToolkit repo when migration is completed.

Details

We are currently maintaining two separate branches of the toolkit, one for UWP and one for WinUI 3/Windows App SDK. This has been done manually and isn't sustainable. We want to take our learnings on creating our new infrastructure with Toolkit Labs for Windows and apply that to our existing code-base to streamline development of the Toolkit moving forward.

First, we would setup a CommunityToolkit/Windows repository that merges the project structure and updates to our processes from Toolkit Labs for Windows with our existing winui code branch. This would involve a lot of effort but also allow us to revitalize our samples and docs for specific features at the same time. It also makes it easier for a developer to focus on specific area within the Toolkit without having to load every Toolkit project or control.

Second, by moving to the new systems in CommunityToolkit/Windows, we would target all platforms within our single CommunityToolkit.WinUI.* based packages and namespaces for both UWP and WinUI 3.

This not only will help streamline our documentation and samples, but make it easier for developers to consume and multi-target XAML for UWP and WinUI 3 in their applications. Library developers can also do the same when building components on top of the Toolkit. We know migrating namespaces is a challenge, however, this incremental step makes migration between UWP and WinUI 3 easier for existing projects in the future as well.

Finally, we would rename or archive the existing CommunityToolkit/WindowsCommunityToolkit repo once the transition has been finalized. This repo would remain to preserve the history of our migration from UWP to a multi-targeted library. The new CommunityToolkit/Windows repo would be pruned to only preserve up-to the conversion from UWP to WinUI 3 (if possible).

Secondary Goals

In addition to the large goals of our releases above in re-working our infrastructure, other work on our samples and docs would need to be done as well. We would investigate if we could bring each Toolkit area over in chunks to re-work each area over time vs. trying to accomplish a giant move in one go. Hopefully this would also allow us to parallelize the work and engage any community members willing to aid in improving our samples and documentation for existing features.

Beyond infrastructure, there are new controls and components that have been worked on already or are already in development. The rest of this issue links out to existing known work that is being developed to track what needs to be migrated or incorporated into the plans above.

Issue Breakdown for 8.0 Release

Milestone Feature Board Bug Board Technical Board Sample Board

Below is a summary of the top level plan items. These items are in addition to everything that was initially released with the preview.

Legend of annotations:

Symbol	Description
:hand:	Help Wanted
:zero:	priority 0 - must have for this release
:one:	priority 1 - nice to have for this release
:two:	priority 2 - stretch goal - unlikely for this release but we will try our best
:grey_exclamation:	missing issue reference
:flashlight:	investigating

Windows Community Toolkit Repo Refactor

These items will track what is required to initialize and setup the new infrastructure with the existing codebase.

• TODO, this needs to be populated after we create infrastructure with Toolkit Labs for Windows.

Book-keeping

• [x] Finalize ColorCode Migration/Transition (Waiting on Legal) - https://github.com/CommunityToolkit/ColorCode-Universal/issues/20
• [x] :flashlight: Discussion: Do we revamp our branding/icons? CommunityToolkit/WindowsCommunityToolkit#3182

Refactors

• [x] :zero: GridSplitter clean-up CommunityToolkit/WindowsCommunityToolkit#2976 (PR CommunityToolkit/WindowsCommunityToolkit#4083)
• [ ] :one: AdaptiveGridView samples to migrate to ItemsRepeater and deprecate
• [x] :one: Clean-up control styles to expose a named Default Style (otherwise it's hard to inherit properly - see TokenizingTextBox/PeoplePicker)

New Features

• [ ] :zero: TransitionHelper for Animations CommunityToolkit/WindowsCommunityToolkit#4323/PR CommunityToolkit/WindowsCommunityToolkit#4338
• [x] :zero: InfoBar StackedNotificationsBehavior CommunityToolkit/WindowsCommunityToolkit#4194/PR CommunityToolkit/WindowsCommunityToolkit#4399
• [x] :zero: Settings Controls (Labs https://github.com/CommunityToolkit/Labs-Windows/issues/216)
• [ ] :zero: ResourceString Markup Extension CommunityToolkit/WindowsCommunityToolkit#4319
• [x] :zero: ContentSizer (as part of GridSplitter refactor above) CommunityToolkit/WindowsCommunityToolkit#2976 (PR CommunityToolkit/WindowsCommunityToolkit#4083)
• [x] :zero: PropertySizer (as part of GridSplitter refactor above) https://github.com/microsoft/microsoft-ui-xaml/issues/190 (PR CommunityToolkit/WindowsCommunityToolkit#4083)
• [ ] ✋ 2️⃣ AdvancedCollectionView Improvements CommunityToolkit/WindowsCommunityToolkit#1128
• [ ] ✋ 2️⃣ RotatorTile OnCurrentItemChanging Event CommunityToolkit/WindowsCommunityToolkit#2994
• [ ] ✋ 2️⃣ Gaze Input Cursor Color CommunityToolkit/WindowsCommunityToolkit#3210

Bugs

• 🔦 Investigate main bugs to call out we want to prioritize here above others.
• [ ] :zero: Performance Option for AttachedShadow CommunityToolkit/WindowsCommunityToolkit#4410/PR CommunityToolkit/WindowsCommunityToolkit#4404
• [ ] :zero: Relative Ancestor CommunityToolkit/Windows#107/PR CommunityToolkit/WindowsCommunityToolkit#4322
• Infinite Canvas

Migration Notes

• [ ] Improve tests for expressions see https://github.com/CommunityToolkit/WindowsCommunityToolkit/pull/4756

[Shomnipotence]

Will it get a new icon?

[michael-hawker]

Will it get a new icon?

Possibly, there has been discussion on this topic in the past CommunityToolkit/WindowsCommunityToolkit#3182. As we get closer to setting a release date for 8.0, it's definitely something we should consider. Thanks for reminding us!

[Nirmal4G]

The namespace for Community Toolkit for Windows with CommunityToolkit.WinUI is too restrictive for what it enables or represents. I propose we move to CommunityToolkit.Windows!

I also have some ideas about repo structure that might not require heavy refactoring when and if we rebrand in the future.

[robloo]

I would like to add back DropShadowPanel and not deprecate it. The dev experience with this control is far superior to the new ideas in AttachedDropShadow which are just wrapping the implementation in composition (which is also poorly designed and doesn't fit in with XAML). AttachedCardShadow is slightly better but missing a lot of properties to control the look.

[Arlodotexe]

The namespace for Community Toolkit for Windows with CommunityToolkit.WinUI is too restrictive for what it enables or represents. I propose we move to CommunityToolkit.Windows!

Plans included supporting WinUI on other platforms, not just Windows, so using WinUI would be more appropriate.

[Nirmal4G]

Okay. But WinUI still represents Windows UI! Also, CommunityToolkit.WinUI.UI is more visually confusing at a glance. It's disturbing (to look at) to say the least.

May be CommunityToolkit.UI.Xaml would be a better alternative…?

[Arlodotexe]

We'll be using CommunityToolkit.WinUI in place of CommunityToolkit.Uwp.UI. When finished, there shouldn't be a CommunityToolkit.WinUI.UI namespace.

[Nirmal4G]

What about the non-UI WinRT namespace CommunityToolkit.Uwp? Seems farfetched to use WinUI here!!

[michael-hawker]

We'll be using CommunityToolkit.WinUI in place of CommunityToolkit.Uwp.UI. When finished, there shouldn't be a CommunityToolkit.WinUI.UI namespace.

There's still a base package without 'UI', but maybe it should just be WinAppSDK. I agree with @Nirmal4G that the current WinUI.UI is a confusing repetition, but we don't have a good solution for this at the moment mapped out. It is something we should figure out within our current naming scheme.

The main thing is that we want the UWP and WinUI packages to be closely aligned enough, but all using the same namespaces for this transition period.

Old Package	New Package UWP	New Package WinUI	Notes
Microsoft.Toolkit	CommunityToolkit.Common	CommunityToolkit.Common	Part of .NET Community Toolkit now, so centralized
Microsoft.Toolkit.Uwp	CommunityToolkit.Uwp	CommunityToolkit.WinAppSDK	This is the problem package at the base
Microsoft.Toolkit.Uwp.UI	CommunityToolkit.Uwp.UI	CommunityToolkit.WinUI	This is the current thing that sparked this conversation to avoid WinUI.UI
Microsoft.Toolkit.Uwp.UI.Controls	CommunityToolkit.Uwp.UI.Controls	CommunityToolkit.WinUI.Controls	Here we can see where the benefits of the collapse would be

Communication the above and how we align namespaces across them would be very weird though, if we expand this table out...

Old Package	Old Namespace	New Package UWP	New Package WinUI	New Aligned Namespace
Microsoft.Toolkit	Microsoft.Toolkit	CommunityToolkit.Common	CommunityToolkit.Common	CommunityToolkit.Common
Microsoft.Toolkit.Uwp	Microsoft.Toolkit.Uwp	CommunityToolkit.Uwp	CommunityToolkit.WinAppSDK	CommunityToolkit.WinAppSDK????
Microsoft.Toolkit.Uwp.UI	Microsoft.Toolkit.Uwp.UI	CommunityToolkit.Uwp.UI	CommunityToolkit.WinUI	CommunityToolkit.WinUI
Microsoft.Toolkit.Uwp.UI.Controls	Microsoft.Toolkit.Uwp.UI.Controls	CommunityToolkit.Uwp.UI.Controls	CommunityToolkit.WinUI.Controls	CommunityToolkit.WinUI.Controls

It gets a bit messy trying to make it streamlined across both UWP and WinAppSDK/WinUI 3.

We also have things like the Connectivity package which needs to wedge between these as well...

[robloo]

Why not "CommunityToolkit.Uwp.UI" and "CommunityToolkit.Win.UI" for example. "Win.UI" makes sense but doesn't follow branding is the only issue I see.

[michael-hawker]

Why not "CommunityToolkit.Uwp.UI" and "CommunityToolkit.Win.UI" for example. "Win.UI" makes sense but doesn't follow branding is the only issue I see.

Yeah, I guess it's a matter of what we align to. We could go like CommunityToolkit.Windows.UI for instance. That may solve the conflicts. Though Windows is pretty broad (though we are the Windows Community Toolkit 😅). It's just that we know we're fairly aligned with building mostly on top of the WinUI platform, so we figured that alignment made more sense from the namespace/packaging perspective.

I mean going with Windows would make everything align nicely... 🤔

Old Package	New Package UWP	New Package WinUI	Namespace
Microsoft.Toolkit	CommunityToolkit.Common	CommunityToolkit.Common	CommunityToolkit.Common
Microsoft.Toolkit.Uwp	CommunityToolkit.Uwp	CommunityToolkit.Windows	CommunityToolkit.Windows
Microsoft.Toolkit.Uwp.Connectivity	CommunityToolkit.Uwp.Connectivity	CommunityToolkit.Windows.Connectivity	CommunityToolkit.Windows.Connectivity
Microsoft.Toolkit.Uwp.UI	CommunityToolkit.Uwp.UI	CommunityToolkit.Windows.UI	CommunityToolkit.Windows.UI
Microsoft.Toolkit.Uwp.UI.Controls	CommunityToolkit.Uwp.UI.Controls	CommunityToolkit.Windows.UI.Controls	CommunityToolkit.Windows.UI.Controls

[robloo]

@michael-hawker

I think Windows perfectly describes the platform the toolkit operates on. WinAppSDK is supposed to encompass a lot of different API's as well bringing them all together under one 'Platform'. WinUI is similar thinking I suppose.

That said, "Windows.UI.Xaml" for example with UWP was supposed to be the be-all-end-all platform as well and took the "Windows" term in a similar way. Look where we are today, so I understand the apprehension.

That said, I think your proposal is the best in terms of naming so far.

[Arlodotexe]

I'd have to again advocate for WinUI here. Using Windows may be nice and clean, but there are many different UI frameworks on Windows.

• WinUI 2 (UWP)
• WinUI 3 (WinAppSDK)
• WPF
• WinForms
• Xamarin/Maui
• React Native
• ..etc.

These specific CommunityToolkit packages have a direct dependency on WinUI 2 and WinUI 3, and none of the other ones.

Taking up the CommunityToolkit.Windows namespace steps on the toes of other frameworks that the CommunityToolkit may support in other packages by suggesting a single unified package that supports them all, which isn't our intent.

[michael-hawker]

I'd have to again advocate for WinUI here. Using Windows may be nice and clean, but there are many different UI frameworks on Windows.

Agree there are many forms of Windows app (thus my initial apprehension going in that direction); but that said, the "Windows App SDK" is the new branding for building Windows apps. And while we do depend on WinUI at the Uwp.UI layer, our current Uwp package and future Windows package would just depend on the Windows App SDK, as we may want to build more off of just that in the future.

I think this may align into a broader discussion of what being a "Windows app" means (FYI @shenchauhan). If documentation from Microsoft and the future the Windows App SDK is trying to bring is around those being the core definition of 'Windows Apps' then our use of 'Windows' in our package names could be justified.

If it encompasses other technologies, then that's more difficult, though easier to distinguish like our partnership with CommunityToolkit.Maui. If other groups want to join the Toolkit family, we could well have a more specific "CommunityToolkit.WPF, or something, in the future, if needed.

In all cases, we're still just defining CommunityToolkit.Windows to be anything built on the Windows App SDK (which is still a justifiable association), and that of course includes our WinUI 3 connection for the majority of our Toolkit work currently.

[jeromelaban]

I agree with @Arlodotexe here, using CommunityToolkit.WinUI seems to be clearer, and more specific to which framework it is targeting.

Yet, following the argument from https://github.com/CommunityToolkit/WindowsCommunityToolkit/issues/4488#issuecomment-1081063575, it should be CommunityToolkit.WinAppSDK.WinUI since there are WinAppSDK apis that are not WinUI specific, but are from a subset of WinAppSDK.

[Arlodotexe]

Yet, following the argument from #4488 (comment), it should be CommunityToolkit.WinAppSDK.WinUI since there are WinAppSDK apis that are not WinUI specific, but are from a subset of WinAppSDK.

Something like that would work for the package names on Nuget, though I think the discussion here is for the namespaces in the libraries, which will all be using the same namespaces as they're multi-targeting UWP, WinAppSDK and Uno.

We just need to agree on what the best choice of namespace is for something like this. The common denominator here without overstepping is WinUI, so that's what my suggestion is.

[michael-hawker]

We just need to agree on what the best choice of namespace is for something like this. The common denominator here without overstepping is WinUI, so that's what my suggestion is.

Yeah, that's the main concern is that we're still bridging this transition. And while CommunityToolkit.WinAppSDK.WinUI may be accurate for the new package (albeit verbose), it's even weirder to use as a namespace for existing UWP projects.

That's where both WinUI and Windows as roots here are more agreeable to being used in both UWP and WinAppSDK projects, are shorter, and not going to be confusing to one set of developers or the other.

[Arlodotexe]

That's where both WinUI and Windows as roots here are more agreeable to being used in both UWP and WinAppSDK projects, are shorter, and not going to be confusing to one set of developers or the other.

Agreed. My main concern is that the Community Toolkit will be very widely used. Windows encompasses more than just UWP and the WinAppSDK, which could cause confusion for Win32, WPF, MAUI, etc.

Also, these packages are now cross-platform thanks to Uno bringing WinUI everywhere, and not explicitly tied to Windows anymore.

[Arlodotexe]

Perhaps a good middle ground would be

• CommunityToolkit.Windows - for any APIs that are tied to the Windows SDK that ships with Windows (WinRT, not Win32).
• CommunityToolkit.Windows.WinUI - for anything that depends on both the Windows SDK and WinUI (2/3)

Though I haven't seen a library that references only the Windows SDK without going through UWP or the WinAppSDK, though. These are both tied to their respective WinUI libraries 🤔

[michael-hawker]

Another thing to consider is that we've already shipped CommunityToolkit.WinUI.* and CommunityToolkit.WinUI.UI versions of these packages for our existing WindowsAppSDK/WinUI 3 support, so if we change the pattern for 8.0, it'll be another breaking change for them (though part of the point of 8.0 is to break this to align for the future, so it's OK to do, but just want to be conscious that we'll have another break).

[Nirmal4G]

@Arlodotexe @jeromelaban

With Windows' current position among Devs, there'll be many more WinUIs and WinAppSDKs come and go but the one thing that'll never change (for the time being) is Windows. Even if you're targeting via Uno, you're still using Windows.* namespaces than Uno.*. Apart from all the internal transliteration that Uno provides, on the surface it's still using Windows API surface.

Hence, IMHO, for all the packages that targets Windows SDK and its derivatives, we can and should go with CommunityToolkit.Windows.* as mentioned here by @michael-hawker. I've been telling this from v7 of the toolkit. Now might be the right time to unify this once and for all and leave it as such for all future releases.

Also, if it were me, I would go with Community.Toolkit or Community.Extensions (just for .NET packages; similar to Microsoft.Extensions). There is also Community.Appkit would apply to App-oriented projects than the generic Community.Toolkit/Extensions would apply to all .NET projects.

Also, having Community.* as a root for all projects that are either related or an extension to projects by M$FT but are maintained by employees or people outside M$FT would be beneficial. This could give Community.* packages an official boost by .NET Foundation and could have a verified tag in the NuGet repository.

VisualStudio is already using Community.* root. See Visual Studio Community Toolkit.

Finally, my advice is the same from the Framework Design Guidelines―Use simple words or existing terminologies to state the intent or purpose of your class identifiers, namespace or assembly names. Make your Root namespaces concise, clear and common.

[michael-hawker]

@Nirmal4G the VS extensions may have chosen to use Community, but there are a few other pre-existing projects that are using Community as a root; so they/we can't take ownership of that to get the 'checkmark' on NuGet. That's why we chose CommunityToolkit as a root to associate directly with our GitHub organization and the .NET Foundation, as you call out as important.

Appreciate your input on the Windows moniker. Definitely need to get some broader input from even more folks on their preferences for us to make a decision here it seems.

[Arlodotexe]

With Windows' current position among Devs, there'll be many more WinUIs and WinAppSDKs come and go

Important to note that this distinction is missing a key point - we're writing WinUI code here. It works under WinAppSDK, UWP and other platforms via Uno, but we're writing code that uses WinUI exclusively.

the one thing that'll never change (for the time being) is Windows

Windows apps can be developed with many other UI frameworks that aren't WinUI. There may one day be toolkits for those (we already have a Maui Community Toolkit), so we need to be mindful of them and not take a namespace which may imply a single package that supports both WinUI and Maui.

[Nirmal4G]

@michael-hawker

NuGet has a concept of multiple owners per root and different owners per sub root. The Community is WE and we are not one person or organization. NuGet could reserve the certain roots like Community and the roots that starts with username as .NET Community or something along the lines.

This is a special case than roots like Microsoft or Windows. You can do the ownership on Community.Toolkit as the root. As I remember, previously we had Microsoft.Toolkit as the root. So, we are only changing from Microsoft to Community. Thus, the change is familiar and understandable.

@Arlodotexe

The word WinUI is just a short form of Windows UI. So, It doesn't make much of a difference. The word WinAppSDK is just a horrible name to put it in namespace or assembly name. However, it could work as a product name.

Let me once again quote myself here:

Finally, my advice is the same from the Framework Design Guidelines―Use simple words or existing terminologies to state the intent or purpose of your class identifiers, namespace or assembly names. Make your Root namespaces concise, clear and common.

MAUI is a different product and we're not using the word MAUI anywhere. So, we're safe here.

[michael-hawker]

@Nirmal4G we can't claim a NuGet sub-root unless we own the root. So, we can't own the root of Community if many different other folks are already using it, as is the case here. That's why we went with CommunityToolkit as it's something specific we could own as a root and delegate sub-roots out as we work with different communities like the MAUI folks.

With Microsoft.Toolkit, Microsoft was still the root. We didn't own either Microsoft or Microsoft.Toolkit as roots we could control. That's why we wanted/needed to create our own root to have greater control over how we could manage our packages on NuGet.

[Arlodotexe]

@Nirmal4G

The word WinUI is just a short form of Windows UI. So, It doesn't make much of a difference.

WinUI is a product name, the name of the UI framework we're using in this repo. It matters when looking for the nuget package that is compatible with the UI framework in your app.

The word WinAppSDK is just a horrible name to put it in namespace or assembly name. However, it could work as a product name.

Agreed. We won't be using WinAppSDK in the namespace, we'll have a single unified CommunityToolkit.WinUI namespace for both WinUI 2 and WinUI 3, which will work under UWP and WinAppSDK respectively.

[Nirmal4G]

@michael-hawker @Arlodotexe

Guess it's a limitation of NuGet. Can't be helped then!

Hmmm... Still don't like the separation between CommunityToolkit.WinUI and CommunityToolkit.Uwp or whatever it ends up. That's why I liked the single Community.Toolkit.Windows namespace.

BTW, the assembly/package names can be different. We can use UWP or WinRT and WinUI moniker on Package and Assembly name while keeping the namespace sane.

With that in mind, I propose we use Community.Toolkit.* for namespace while CommunityToolkit.* for the assembly/package names.

[michael-hawker]

To clarify, the current thinking/plan will be that we'll have a singular namespace, e.g. CommunityToolkit.WinUI.* (or whatever) but two sets of packages under: CommunityToolkit.UWP.* for UWP and CommunityToolkit.WinUI.* for WinUI 3.

This would help with interop and migration of moving from UWP to WinUI 3 as the namespaces will be aligned, and allows us the opportunity to merge with Uno in the future and support Uno + UWP and Uno + WinUI 3 via the independent packages. Unfortunately we can't have a single package support all combinations.

I think since we're the CommunityToolkit organization keeping the root namespace as CommunityToolkit would still make sense though as the first part of a namespace is typically the organization name.

[Nirmal4G]

@michael-hawker

The WinUI can be for UI APIs but what about the non-UI APIs? Will they use the existing UWP or older WinRT or something else?

I recommend using Windows in the namespace as you proposed previously as it unifies nicely. But we can use different moniker on assembly/package names.

I do agree that CommunityToolkit is more of a vendor name in the namespace. Having to separate the words gives you more freedom to have a certain areas of code to be put under different namespace with the Community domain.

Let's say, may be in future, you want a separate namespace for experimental code or a work-in-progress extension for a existing feature, you can put those under Community.Preview.* or Community.Extensions.* before moving those into Community.Toolkit. Even Windows APIs follow a pattern like this.

IMO, Even CommunityToolkit is too generic. So, it doesn't matter if we separate those words at the namespace level. It only gives more room for code that can't be put under Toolkit. We can still keep the CommunityToolkit name everywhere else except in namespace.

[Arlodotexe]

The WinUI can be for UI APIs but what about the non-UI APIs? Will they use the existing UWP or older WinRT or something else?

I'll re-post this from above for consideration:

---

Perhaps a good middle ground would be

• CommunityToolkit.Windows - for any APIs that are tied to the Windows SDK that ships with Windows (WinRT, not Win32).
• CommunityToolkit.Windows.WinUI - for anything that depends on both the Windows SDK and WinUI (2/3)

Though I haven't seen a library that references the Windows SDK without going through UWP or the WinAppSDK, though. These are both tied to their respective WinUI libraries 🤔