Repository navigation
Breaking API changes that have to be done before next major release #3538
Description
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:
- transform
[InternalApi]
public Something()to
internal Something()- 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.Instancestatic 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)
ItemsControlitem 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
LocalValueSet 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)
Activity
Shayan-To commentedon Nov 10, 2020
Is Avalonia using / going to use
Microsoft.Extensionspackages for configurations, dependency injection, etc.?kekekeks commentedon Nov 10, 2020
The generic host model provided by
Microsoft.Extensionsisn't really suitable for Avalonia needs, unfortunatelyDependency injection should be managed managed by MVVM framework (Prism, ReactiveUI, etc), not the UI toolkit.
koalarcoder commentedon Jun 3, 2021
when will we have 1.0 version,thank you
fubar-coder commentedon Nov 11, 2021
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 commentedon Mar 16, 2022
I think
ContextMenushould now be removed as it is better replaced withContextFlyoutwhich can host aMenuFlyout. This moves from the WPF way of doing things to the UWP way which is better generalized and more powerful.kekekeks commentedon Mar 16, 2022
IIRC we've decided to keep ContextMenu as a legacy but still supported API to simplify porting from WPF
robloo commentedon Mar 16, 2022
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 commentedon Apr 2, 2022
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 commentedon May 30, 2022
I just noticed the
TextBlocksforDatePickerare calledDayText,MonthTextandYearText. ForTimePickerhowever, they are calledMinuteTextBlockandHourTextBlock. Maybe this is something which should be unified for the next major release.maxkatz6 commentedon May 30, 2022
@CollinAlpert it's just a x:Name properties? Yes, it can be changed with no problems, if you want to create a PR.
CollinAlpert commentedon May 30, 2022
@maxkatz6 it's also a
TemplatePart, so some users might use it in styling. That would break if the name changes.robloo commentedon May 30, 2022
@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 commentedon Sep 11, 2022
Roll-up of some things I think should be addressed:
[-]Breaking API changes that have to be done before 1.0 release[/-][+]Breaking API changes that have to be done before next major release[/+]