Planning and assessing the full 7.x to 8.x map

[Arlodotexe]

Background

The move from WCT 7 to 8 was an overhaul that saw:

• A new (cleaner) package setup and a unified namespace
• Consolidation of the UWP and WinUI 3 versions of the toolkit into a single codebase, plus the addition of Uno support
• Complete rewrite of our core dev loop, making it easier to build new components, add docs, make samples and write tests
• A port of our most used components from 7.x to 8.x
• Rewrites or refactors of the most used components that needed it
• The introduction of WCT Labs, using the new tooling for rapid component prototyping and incubation.
• New components like GridSplitter/ContentSizer, SegmentedControl, SettingsControls, etc.

Note the use of 'most used' in the above. This was a major undertaking, so some of the seldom used components from 7.x were de-prioritized to give the opportunity for a proper review/refactor.

Rather than blindly porting the existing code, we're gathering usage scenarios and porting requests across projects that still need and use them, and we're making proactive improvements to the components that need it in the process. The ones that were most used and needed it got the refactor/rewrite (e.g. DataTable, MarkdownTextBlock, ColorPicker, storage helpers), but the ones that were seldom used are still waiting.

Many of these should already have open tracking tickets, such as BladeView, but some haven't been raised or otherwise fell under the radar. We don't see requests for these less-used components often, but we like to take note when we do.

Now that things are settling down as we approach 8.2, over the next week or so I'm hoping to pull together the full map and a cross-analysis of everything between 8.x and 7.x to fill the remaining tracking gaps for us. For some of them, we may opt to use Labs to make improvements first if needed.

Problem

A comprehensive comparison between WCT 7.x and 8.x is needed across all areas. Not just a "port checklist", but a proper breakdown that includes the rationale for things that were made obsolete or rewritten or refactored during port.

Additionally, building this map to completeness will give us a birds-eye view of the different code areas in the toolkit, which will be generally useful for planning.

Solution

The transition to WCT 8 introduced significant architectural changes, including rearranging where you'd find docs, tests and samples, and including consolidating the Uwp and WinUI code with optional consideration to Uno. Understanding these changes is crucial for proper analysis.

To proceed, we'll need to identify both what and where for both 7.x and 8.x.

Evaluate the areas to map

Starting with where:

• Identify components to map
• Identify each component sub-area to map
  • Source code
  • Docs and samples
  • Tests

These will provide us a high-level map of both 7.x and 8.x, which will facilitate the "porting map" between them and allow us to identify gaps in either.

These separate maps will also act as our "birds-eye" view for the different areas across components in the toolkit.

Evaluate the state of each

With a full list of components in both 7.x and 8.x in hand, we need to assess what the current state is for each-- whether each sub-area (source, docs, tests) is ported, planned, unplanned, in progress, undecided, superseded, etc.

Notably, a planned port could be a direct port, a light refactor, or a full-on rewrite.

Existing tickets should be linked wherever possible, missing tickets should be filed as necessary, and rationale should be provided whenever possible.

With this simple map, we can visit each area/where (source, docs, tests) in each component and assess what task types that needs done depending on the state of the map.

Assess the migration strategy

For components that still need to be ported/migrated to 8.x, we outline the areas to consider when assessing the migration strategy.

Several components were already successfully rewritten or refactored during the initial port. This experience should inform our approach to remaining components.

Investigate per component:
Previous successful rewrites (DataTable, MarkdownTextBlock, ColorPicker) can provide templates for different migration approaches.

• Direct port feasibility: If the code is straightforward, highly maintainable and has no API issues or lingering refactors that need resolved, then a direct port could be possible.
• Interim improvements: Even with a direct port, we might want to make minor interim improvements such as style updates. These can be done without significant breaking changes or refactors.
• Rewrite/refactor justifications (Labs): WCT Labs was introduced specifically for component prototyping and incubation. This provides a pathway for components needing significant updates, refactors or even entire rewrites.
• Accommodating for differences between UWP / WinUI 3 / Uno: In 7.x, the WCT team maintained a branch for UWP, a branch for WinUI, and the Uno team managed their own fork. In 8.x, we consolidated the differences into a single codebase. These differences should be accommodated when porting any code.

Closing notes

This document defines a clear strategy for assessing the full 7.x and 8.x map and planning porting tasks from 7.x to 8.x.

Creating the 8.x map separately allows it to also be used to inform our higher-level planning processes, especially being composed of GitHub issues and making careful use of the label system. Some of the needed labels may be missing, but this formalized labeling system should have everything we need. We can create new labels if needed.