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