Breaking API changes that have to be done before next major release

[kekekeks]

This is a tracking issue

While Avalonia is ready for use, we can't really claim that it's 1.0 when we know that certain areas have to be changed in incompatible ways to work properly on various platforms and in various environments.

There will most likely be 0.10, 0.11 and probably 0.12 releases, but for widespread Avalonia adoption we need a promise of long-term API stability.

After 1.0 we'll still be allowed to deprecate things, but we'll have to keep a compatibility layer for several releases after a feature was deprecated.

So one of the goals in 2020 and probably the start of 2021 would be to focus on such "breaking-change-prone" areas so we could finally release the long awaited 1.0.

Public API contract note

Everything with Impl suffix is considered a private implementation detail without any API/ABI compatibility guarantees whatsoever (BTW, we need to add a wrapper for IClipboardImpl, it's been years already). Those can change in any way even in minor version releases.

Stuff in platform backens other than XXXPlatformOptions and UseXXX is also not considered to be a stable API. If we need something platform-specific, we still need an API that's not bound to a platform backend. So in general platform backends shouldn't have any public types, unless those are required to setup/configure the backend.

Solution-wide internal APIs

We are likely to have some helper methods or classes, that are reusable in the code base, but don't necessary have to be included in the public API contract. So we probably need some kind of Cecil-based post-processing, that would:

1. transform

[InternalApi]
public Something()

to

internal Something()

2. add [InternalsVisibleTo] attributes

That would ensure that project-private APIs wont be leaked, but non-public API parts would be still hidden.

Another way is to transform [Internal] to [Obsolete("This API is considered to be private to Avalonia and can be changed in incompatible way at any time")].

Known areas that would cause breaking changes:

• Un-global everything (we could still keep things backed by AvaloniaLocator, just make sure to remove XXX.Instance static properties and move everything to TopLevel's
• Text input
• Control themes
• Drag-n-Drop (the current API is win32-centric and most likely won't map nicely to other platforms)
• ItemsControl item container generation API will be changed by WIP: Use ItemsRepeater as base for ItemsPresenter #3388
• Merging native menus and managed menus into a more user-friendly API Menus redesign #3855
• Make template-applied properties use a lower priority than LocalValue Set Template-provided properties with a separate BindingPriority #2789

Things to investigate:

• Changes needed for Wayland protocol support (preferably with a prototype)
• Changes needed for iOS/Android support (aside from ones listed in the roadmap)

[Shayan-To]

Is Avalonia using / going to use Microsoft.Extensions packages for configurations, dependency injection, etc.?

[kekekeks]

The generic host model provided by Microsoft.Extensions isn't really suitable for Avalonia needs, unfortunately

Dependency injection should be managed managed by MVVM framework (Prism, ReactiveUI, etc), not the UI toolkit.

[koalarcoder]

when will we have 1.0 version,thank you

[fubar-coder]

Regarding internal APIs: Microsoft uses special "ref" assemblies (e.g. for Microsoft.Extensions.Configuration.Abstractions). This allows a very fine control regarding the API to be exposed.

EDIT: This also means that you can still have "internal" code which is defined as public, but is not available when consumed via nuget.

[robloo]

I think ContextMenu should now be removed as it is better replaced with ContextFlyout which can host a MenuFlyout. This moves from the WPF way of doing things to the UWP way which is better generalized and more powerful.

[kekekeks]

IIRC we've decided to keep ContextMenu as a legacy but still supported API to simplify porting from WPF

[robloo]

IIRC we've decided to keep ContextMenu as a legacy but still supported API to simplify porting from WPF

I know when Flyout was implemented and ContextMenu was marked as obsolete there was some uproar. ContextMenu was quickly un-obsoleted. I hope that isn't the permanent plan though.

[jogibear9988]

You could also declare the classes as "internal" and use them from other assemblies via:
https://github.com/aelij/IgnoresAccessChecksToGenerator

aelij uses this in roslynpad to access internals of roslyn

[CollinAlpert]

I just noticed the TextBlocks for DatePicker are called DayText, MonthText and YearText. For TimePicker however, they are called MinuteTextBlock and HourTextBlock. Maybe this is something which should be unified for the next major release.

[maxkatz6]

@CollinAlpert it's just a x:Name properties? Yes, it can be changed with no problems, if you want to create a PR.

[CollinAlpert]

@maxkatz6 it's also a TemplatePart, so some users might use it in styling. That would break if the name changes.

[robloo]

@CollinAlpert If its a template part I recommend adding the PART_ prefix as well while you are at it. Otherwise, I'll get to it later.

[robloo]

Roll-up of some things I think should be addressed:

• Finally mark ContextMenu as [Obsolete] by flyout. Remove this in 12.0 or something altogether with the menu rewrites.
• Items vs ItemsSource breaking change
• Parents clipping children by default with the new composition render (I think this is supported just not enabled by default). UWP different from WPF here and UWP/WinUI is a lot more intuitive.