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

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()

1. 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 #3388
• Merging native menus and managed menus into a more user-friendly API #3855
• Make template-applied properties use a lower priority than LocalValue #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)

[koalarcoder]

when will we have 1.0 version,thank you

[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.