Uno Platform — Breaking-Changes Rollout (Epic #8339)

Ordered, danger-ranked checklist for the next major. Items are sequenced least dangerous first (native-only & dead code) to most dangerous last (pervasive type-system changes). Each unchecked item is meant to be picked up by a single subagent in its own worktree.

Generated 2026-06-15 from a per-item investigation of the current dev/mazi/breaking worktree (see assessments-raw.json for the raw danger/effort/impact data behind every line).

Ground rules (decided)

Hard-remove everything now — no [Obsolete]/[EditorBrowsable] deprecation shims. This is THE breaking major; many items have been pending since 2022.
Match WinUI exactly — when reducing visibility / changing signatures, the target shape is the WinUI one. Do not invent intermediate Uno-only surfaces. Native divergences are removed, not preserved.
Native targets are being dropped (native Android Views, iOS/UIKit, WASM DOM). Native-only changes are therefore very safe and ship first. Non-UI WinRT APIs in Uno.UWP/Uno.Foundation are NOT being dropped (Skia-on-Android still consumes them) — those are judged on normal merit.
The 5 pervasive type-system items get their own impact specs (BC14, BC26, BC38, BC58 + BC54 folded into BC58) with Pros/Cons. They ship last, one stabilized PR each.
Validate at runtime, not compile-only. For anything that changes behaviour (Phase 5 especially) prove it with a runtime test that fails-before/passes-after.

How a subagent picks up an item

Take the topmost unchecked item (respect the cross-item ordering in the watchlist below).
Spin up a worktree; make the change per the item's action note + its WinUI reference.
Build the relevant Skia slice; run/extend runtime tests; for behavioural items add a fails-before/passes-after test.
One focused Conventional-Commit PR per item, referencing #8339. Check the box here.

Legend: dN = danger 1 (safest) → 5 (most dangerous) · S/M/L = effort · ⚠️ = has an open decision/verify-first flag (see the item note).

Phase 1 — Native-only removals & inert dead-code

Danger 1. The safe vanguard: deletions scoped to native targets being dropped, plus orphaned public stubs with zero consumers. Cannot affect Skia runtime. Ship as one batch.

Phase 2 — Native-only public-API removals

Danger 2. Native-scoped, but delete public members a Skia user still sees in IntelliSense / compiles against. Native rendering is gone so the symbols are meaningless; hard-remove.

BC23 — Remove AdaptNative native-hosting path d2·S
- Hard-remove the public AdaptNative/TryAdaptNative surface (native hosting gone).
- Files: src/Uno.UI/UI/Xaml/Media/VisualTreeHelper.cs, src/Uno.UI/UI/Xaml/UIElementCollectionExtensions.Xamarin.cs, src/Uno.UI/UI/Xaml/Controls/Border/Border.cs
BC66 — Remove Android Window.IsStatusBarTranslucent() d2·S
- Hard-remove the public Android Window.IsStatusBarTranslucent(); repoint the internal consumer to NativeWindowWrapper.
- Files: src/Uno.UI/UI/Xaml/Window/Window.Android.cs, src/Uno.UI/UI/Xaml/Window/Native/NativeWindowWrapper.Android.cs, src/Uno.UI/UI/Xaml/Controls/ComboBox/ComboBox.custom.cs

Phase 3 — Internal feature-flag, dead-code & shim removals

Danger 2. Cross-target but low blast radius: delete always-on/off flags (inline the live branch), dead helpers, binary-compat shims, no-op members. Behaviour unchanged on defaults. The Setter pipeline trio BC37 -> BC44 -> BC63 must land adjacently in that order.

Phase 4 — Visibility reductions & signature/rename tweaks

Danger 2. Tighten Uno-only public surface to match WinUI (internal/protected/sealed/explicit-interface/hide) plus tiny signature & typo fixes. Each is narrow and independent; effort S. Ideal single sweep.

Phase 5 — Behavioural defaults, base-class & type tweaks

Danger 3. Wider but localized: visibility on more-derivable hooks, per-type base-class realignments, enum/type-shape changes, and behaviour-changing defaults. Several silently change runtime behaviour even on defaults — gate each on a migration note + runtime/visual validation, not compile-only.

Phase 6 — Larger structural moves & legacy-mechanism removal

Danger 3-4. Heavier multi-file changes: remove the legacy templated-parent mechanism, repurpose the precedence enum, tear down Fluent V1 scaffolding, rename the Toolkit assembly, and remove the legacy Windows.UI.Input.* surface. Each is its own PR.

BC01 — Remove legacy templated-parent mechanism d3·L · #18672
- Hard-remove legacy path incl. public FrameworkTemplateBuilder delegate + legacy ctors. First fix the tests that currently force _isLegacyTemplate=true.
- Files: src/Uno.UI/UI/Xaml/FrameworkTemplate.cs, src/Uno.UI/UI/Xaml/TemplatedParentScope.cs, src/Uno.UI/UI/Xaml/ControlTemplate.cs
BC39 — Clean up DependencyPropertyValuePrecedences enum d2·M · PR #15684
- Hard-remove obsolete enum members (no [EditorBrowsable] aliases).
- Files: src/Uno.UI/UI/Xaml/DependencyPropertyValuePrecedences.cs, src/Uno.UI/UI/Xaml/DependencyObjectStore.cs, src/Uno.UI/UI/Xaml/Internal/DependencyPropertyHelper.cs
BC71 — Remove Fluent V1 public surface d2·M · #14765
- Hard-remove XamlControlsResourcesV1 + ControlsResourcesVersion.Version1 + build/package scaffolding (V1 content is already gone).
- Files: src/Uno.UI.FluentTheme.v1/XamlControlsResourcesV1.cs, src/Uno.UI.FluentTheme.v1/Uno.UI.FluentTheme.v1.Skia.csproj, src/Uno.UI.FluentTheme.v1/Uno.UI.FluentTheme.v1.Wasm.csproj
BC53 — Rename Uno.UI.Toolkit assembly/namespace ⚠️ d4·M · #12322
- DECIDE the new assembly/namespace name. Hard rename, no type-forwarders / xmlns alias (per hard-remove policy).
- Files: src/Uno.UI.Toolkit/, src/Uno.UI.Toolkit/Uno.UI.Toolkit.Skia.csproj, src/Uno.UI.Toolkit/Uno.UI.Toolkit.Wasm.csproj
BC76 — Remove/internalize Windows.UI.Input.* (~173 types) d4·M · #18875
- Hard-remove the ~173 stub types. The real InputInjector family (test infra) -> move to Microsoft.UI.Input.Preview.Injection and update call sites.
- Files: src/Uno.UWP/Generated/3.0.0.0/Windows.UI.Input, src/Uno.UWP/Generated/3.0.0.0/Windows.UI.Input.Spatial, src/Uno.UWP/Generated/3.0.0.0/Windows.UI.Input.Inking

Phase 7 — Pervasive type-system changes (each has its own impact spec)

Danger 4-5. Ship last, never batched — each lands as its own separately-stabilized PR with full runtime-test passes. See the dedicated spec per item for Pros/Cons and impact.

BC58 — DataContext on FrameworkElement only d4·M · #13201 · impact spec
- Adjust signature to match WinUI.
- Files: src/SourceGenerators/Uno.UI.SourceGenerators/DependencyObject/DependencyObjectGenerator.cs, src/Uno.UI/UI/Xaml/DependencyObjectStore.Binder.cs, src/Uno.UI.UnitTests/DependencyProperty/Given_DependencyProperty.DataContext.cs
BC54 — FlyoutBase.DataContext -> non-public d4·L · #12491
- Keep DataContext internal so FlyoutBase->Popup forwarding still works; hide only the public surface. Folded into the BC58 spec.
- Files: src/SourceGenerators/Uno.UI.SourceGenerators/DependencyObject/DependencyObjectGenerator.cs, src/Uno.UI/UI/Xaml/Controls/Flyout/FlyoutBase.cs, src/Uno.UI/UI/Xaml/DependencyObjectStore.Binder.cs
BC26 — DependencyObject becomes a class d4·L · #17099 · impact spec
- See notes.
- Files: src/Uno.UI/UI/Xaml/DependencyObject.cs, src/SourceGenerators/Uno.UI.SourceGenerators/DependencyObject/DependencyObjectGenerator.cs, src/Uno.UI/UI/Xaml/UIElement.skia.cs
BC14 — UserControl inherits Control d5·L · impact spec
- Reparent to match WinUI.
- Files: src/Uno.UI/UI/Xaml/Controls/UserControl/UserControl.cs, src/Uno.UI/UI/Xaml/Controls/Page/Page.cs, src/Uno.UI/UI/Xaml/Controls/ContentControl/ContentControl.cs
BC38 — Move Background FrameworkElement -> Control d4·L · impact spec
- Reparent to match WinUI.
- Files: src/Uno.UI/UI/Xaml/FrameworkElement.Interface.skia.cs, src/Uno.UI/UI/Xaml/FrameworkElement.Interface.wasm.cs, src/Uno.UI/UI/Xaml/FrameworkElement.Interface.reference.cs

Standalone — large but low runtime-risk (run anytime)

BC59 — Enable nullable reference types by default d1·L · #9964
- Standalone. Flip <Nullable>enable</Nullable> globally + annotate ~4300 files. Low runtime risk, large churn; can run anytime independent of the phases.
- Files: src/Directory.Build.props, src/Uno.UI/Uno.UI.Skia.csproj, src/Uno.UI/Uno.UI.Reference.csproj

Sequencing watchlist

Setter pipeline (Phase 3): BC37 (remove CLR-property Setter codegen) → BC44 (remove Setter<T>) → BC63 (remove SetterBase.set_Property). Land adjacently, in order.
DataContext / DependencyObject (Phase 7): do BC58 (generator-wide DataContext->FE-only) first; it gates BC54 (FlyoutBase symptom) and de-risks BC26 (DependencyObject->class). All touch the same generated DO mixin.
Background / UserControl (Phase 7): BC38 (Background -> Control) precedes BC14 (UserControl -> Control) so the property relocation is not redone.
Behaviour-drift items (validate at runtime): BC50 (culture no longer changes on setter), BC45 (Center/Center default), BC74 (drawable key collision), BC42 (drop clr-namespace:), BC51 (ms-resource:/// rewrite) — each changes runtime behaviour even for default users.
Verify-first / open-decision items: BC07 (maybe already removed), BC16 (struct design maybe obsolete), BC21 (line ref drifted; may drop), BC53 (needs a new name), BC55 (must preserve the prefs backing file).

Appendix A — Already done / obsolete (verify & check off, no work expected)

BC03 — BaseActivity.Current annotated nullable — moot (native drop) · PR #18582
- Still technically applies (the file keeps the non-nullable public static BaseActivity Current), but BaseActivity.Android.cs is a native-Android host file deleted wholesale when native targets drop — no separate task needed. PR #18582 was closed unmerged (2025-09-15, touched only that file, +3/-1).
BC56 — Remove Android EnableExperimentalKeyboardFocus — already-done
- The Android-specific removal this item describes is already implemented. In WinRTFeatureConfiguration.Focus.cs the property is gated #if __IOS__ || __TVOS__ (line 7) and its XML doc already says "keyboard focus is now always enabled on An
BC77 — Adjust Android conditionals — already-done · PR #12563
- Verified against the live worktree: grep for __ANDROID_\d+__ across all of src returns ZERO matches, so every numbered conditional this PR targeted is already gone. Spot-checked the representative cases: BindableGridView.Android.cs no lon
BC78 — BorderLayerRenderer refactor — already-done · PR #12593
- PR #12593 is CLOSED, but the refactor it proposed has already landed on this branch. Commit 3887af4454 ("refactor: Move border-related properties into a IBorderInfoProvider") plus follow-ups (a0018d8a1d, 3c16c1fc64, f32e017186, dced5e6424)
BC10 — ItemsControl.OnItemsChanged parameter type — obsolete · (WinUI already matches)
- Located at src/Uno.UI/UI/Xaml/Controls/ItemsControl/ItemsControl.cs:254 — protected virtual void OnItemsChanged(object e). The internal caller OnItemsVectorChanged (line 90-93) does pass an IVectorChangedEventArgs into it, which is presum
BC68 — WinUI sync-generator fix — obsolete · PR #13867
- PR #13867 ("fix: WinUI sync generator", CLOSED, by Youssef1313, labeled stale) modified the old UWPSyncGenerator/DocGenerator tooling to emit a WinUI/WinAppSDK API surface. Searched the repo: there is NO UWPSyncGenerator project or any refe
BC79 — Brush change-subscription perf — obsolete · PR #12595
- PR #12595 is CLOSED (WIP perf, authored by MartinZikmund, replaced #12234). It added an internal closure-free brush-change subscription (SubscribeToChanges, BrushChangedCallback delegate, BrushChangedDisposable, RaiseBrushChanged) and migra

BC54 is listed in Phase 7 but has no standalone task — it is implemented as part of BC58.

Navigation Menu

Uh oh!

Uno Platform — Breaking-Changes Rollout (Epic #8339)

Ground rules (decided)

How a subagent picks up an item

Phase 1 — Native-only removals & inert dead-code

Phase 2 — Native-only public-API removals

Phase 3 — Internal feature-flag, dead-code & shim removals

Phase 4 — Visibility reductions & signature/rename tweaks

Phase 5 — Behavioural defaults, base-class & type tweaks

Phase 6 — Larger structural moves & legacy-mechanism removal

Phase 7 — Pervasive type-system changes (each has its own impact spec)

Standalone — large but low runtime-risk (run anytime)

Sequencing watchlist

Appendix A — Already done / obsolete (verify & check off, no work expected)

Uh oh!

FilesExpand file tree

spec.md

Latest commit

History

spec.md

File metadata and controls

Uno Platform — Breaking-Changes Rollout (Epic #8339)

Ground rules (decided)

How a subagent picks up an item

Phase 1 — Native-only removals & inert dead-code

Phase 2 — Native-only public-API removals

Phase 3 — Internal feature-flag, dead-code & shim removals

Phase 4 — Visibility reductions & signature/rename tweaks

Phase 5 — Behavioural defaults, base-class & type tweaks

Phase 6 — Larger structural moves & legacy-mechanism removal

Phase 7 — Pervasive type-system changes (each has its own impact spec)

Standalone — large but low runtime-risk (run anytime)

Sequencing watchlist

Appendix A — Already done / obsolete (verify & check off, no work expected)