Added attributes describing API stability.

Adds two attributes which describe the stability of an API:

- `UnstableAttribute` indicates that we provide no API stability guarantees for the class between minor/patch versions. This is mostly applied to `*Impl` interfaces which describe the interface between core Avalonia and platform implementations
- `NotClientImplementableAttribute` indicates that an interface is stable for consumption by a client, but should not be implemented outside of Avalonia itself (either because custom implementations are not supported, or because as members may be added to its API)

build/ApiCompatAttributeExcludeList.txt

@@ -0,0 +1,2 @@
+T:Avalonia.Metadata.NotClientImplementableAttribute
+T:Avalonia.Metadata.UnstableAttribute

src/Avalonia.Base/Animation/IAnimation.cs

@@ -1,12 +1,14 @@
 using System;
 using System.Threading;
 using System.Threading.Tasks;
+using Avalonia.Metadata;
 
 namespace Avalonia.Animation
 {
     /// <summary>
     /// Interface for Animation objects
     /// </summary>
+    [NotClientImplementable]
     public interface IAnimation
     {
         /// <summary>

src/Avalonia.Base/Animation/IAnimationSetter.cs

@@ -1,5 +1,8 @@
+using Avalonia.Metadata;
+
 namespace Avalonia.Animation
 {
+    [NotClientImplementable]
     public interface IAnimationSetter
     {
         AvaloniaProperty? Property { get; set; }

src/Avalonia.Base/Animation/IAnimator.cs

@@ -1,11 +1,13 @@
 using System;
 using System.Collections.Generic;
+using Avalonia.Metadata;
 
 namespace Avalonia.Animation
 {
     /// <summary>
     /// Interface for Animator objects
     /// </summary>
+    [NotClientImplementable]
     public interface IAnimator : IList<AnimatorKeyFrame>
     {
         /// <summary>

src/Avalonia.Base/Animation/IClock.cs

@@ -1,9 +1,9 @@
 using System;
-using System.Collections.Generic;
+using Avalonia.Metadata;
-using System.Text;
 
 namespace Avalonia.Animation
 {
+    [NotClientImplementable]
     public interface IClock : IObservable<TimeSpan>
     {
         PlayState PlayState { get; set; }

src/Avalonia.Base/Animation/IGlobalClock.cs

@@ -1,9 +1,8 @@
-using System;
+using Avalonia.Metadata;
-using System.Collections.Generic;
-using System.Text;
 
 namespace Avalonia.Animation
 {
+    [NotClientImplementable]
     public interface IGlobalClock : IClock
     {
     }

src/Avalonia.Base/Animation/ITransition.cs

@@ -1,10 +1,12 @@
 using System;
+using Avalonia.Metadata;
 
 namespace Avalonia.Animation
 {
     /// <summary>
     /// Interface for Transition objects.
     /// </summary>
+    [NotClientImplementable]
     public interface ITransition
     {
         /// <summary>

src/Avalonia.Base/Controls/INameScope.cs

@@ -1,5 +1,4 @@
-using System;
+using Avalonia.Metadata;
-using System.Threading.Tasks;
 using Avalonia.Utilities;
 
 namespace Avalonia.Controls
@@ -7,6 +6,7 @@ namespace Avalonia.Controls
     /// <summary>
     /// Defines a name scope.
     /// </summary>
+    [NotClientImplementable]
     public interface INameScope
     {
         /// <summary>

src/Avalonia.Base/Controls/IPseudoClasses.cs

@@ -1,9 +1,11 @@
+using Avalonia.Metadata;
 
 namespace Avalonia.Controls
 {
     /// <summary>
     /// Exposes an interface for setting pseudoclasses on a <see cref="Classes"/> collection.
     /// </summary>
+    [NotClientImplementable]
     public interface IPseudoClasses
     {
         /// <summary>

src/Avalonia.Base/Controls/IResourceHost.cs

@@ -1,6 +1,5 @@
 using System;
-
+using Avalonia.Metadata;
-#nullable enable
 
 namespace Avalonia.Controls
 {
@@ -10,6 +9,7 @@ namespace Avalonia.Controls
     /// <remarks>
     /// This interface is implemented by <see cref="StyledElement"/> and `Application`.
     /// </remarks>
+    [NotClientImplementable]
     public interface IResourceHost : IResourceNode
     {
         /// <summary>

src/Avalonia.Base/Controls/IResourceNode.cs

@@ -1,6 +1,5 @@
 using System;
-
+using Avalonia.Metadata;
-#nullable enable
 
 namespace Avalonia.Controls
 {
@@ -12,6 +11,7 @@ namespace Avalonia.Controls
     /// (<see cref="IResourceHost"/>) and resource providers such as <see cref="ResourceDictionary"/>
     /// (see <see cref="IResourceProvider"/>).
     /// </remarks>
+    [NotClientImplementable]
     public interface IResourceNode
     {
         /// <summary>

src/Avalonia.Base/Controls/ISetInheritanceParent.cs

@@ -1,4 +1,4 @@
-#nullable enable
+using Avalonia.Metadata;
 
 namespace Avalonia.Controls
 {
@@ -10,6 +10,7 @@ namespace Avalonia.Controls
     /// Additionally, <see cref="ISetLogicalParent"/> also sets the inheritance parent; this
     /// interface is only needed where the logical and inheritance parents differ.
     /// </remarks>
+    [NotClientImplementable]
     public interface ISetInheritanceParent
     {
         /// <summary>

src/Avalonia.Base/Controls/ISetLogicalParent.cs

@@ -1,6 +1,5 @@
 using Avalonia.LogicalTree;
-
+using Avalonia.Metadata;
-#nullable enable
 
 namespace Avalonia.Controls
 {
@@ -10,6 +9,7 @@ namespace Avalonia.Controls
     /// <remarks>
     /// You should not usually need to use this interface - it is for advanced scenarios only.
     /// </remarks>
+    [NotClientImplementable]
     public interface ISetLogicalParent
     {
         /// <summary>

src/Avalonia.Base/Data/Core/IPropertyInfo.cs

@@ -1,7 +1,9 @@
 using System;
+using Avalonia.Metadata;
 
 namespace Avalonia.Data.Core
 {
+    [NotClientImplementable]
     public interface IPropertyInfo
     {
         string Name { get; }

src/Avalonia.Base/Data/IBinding.cs

@@ -1,8 +1,11 @@
+using Avalonia.Metadata;
+
 namespace Avalonia.Data
 {
     /// <summary>
     /// Holds a binding that can be applied to a property on an object.
     /// </summary>
+    [NotClientImplementable]
     public interface IBinding
     {
         /// <summary>

src/Avalonia.Base/IAvaloniaObject.cs

@@ -1,11 +1,13 @@
 using System;
 using Avalonia.Data;
+using Avalonia.Metadata;
 
 namespace Avalonia
 {
     /// <summary>
     /// Interface for getting/setting <see cref="AvaloniaProperty"/> values on an object.
     /// </summary>
+    [NotClientImplementable]
     public interface IAvaloniaObject
     {
         /// <summary>

src/Avalonia.Base/IDataContextProvider.cs

@@ -1,10 +1,11 @@
-#nullable enable
+using Avalonia.Metadata;
 
 namespace Avalonia
 {
     /// <summary>
     /// Defines an element with a data context that can be used for binding.
     /// </summary>
+    [NotClientImplementable]
     public interface IDataContextProvider : IAvaloniaObject
     {
         /// <summary>

src/Avalonia.Base/IDirectPropertyAccessor.cs

@@ -1,4 +1,5 @@
 using System;
+using Avalonia.Metadata;
 
 namespace Avalonia
 {

src/Avalonia.Base/IDirectPropertyMetadata.cs

@@ -1,8 +1,11 @@
+using Avalonia.Metadata;
+
 namespace Avalonia
 {
     /// <summary>
     /// Untyped interface to <see cref="DirectPropertyMetadata{TValue}"/>
     /// </summary>
+    [NotClientImplementable]
     public interface IDirectPropertyMetadata
     {
         /// <summary>

src/Avalonia.Base/IStyledElement.cs

@@ -2,12 +2,12 @@
 using System.ComponentModel;
 using Avalonia.Controls;
 using Avalonia.LogicalTree;
+using Avalonia.Metadata;
 using Avalonia.Styling;
 
-#nullable enable
-
 namespace Avalonia
 {
+    [NotClientImplementable]
     public interface IStyledElement :
         IStyleable,
         IStyleHost,

src/Avalonia.Base/IStyledPropertyMetadata.cs

@@ -1,8 +1,11 @@
+using Avalonia.Metadata;
+
 namespace Avalonia
 {
     /// <summary>
     /// Untyped interface to <see cref="StyledPropertyMetadata{TValue}"/>
     /// </summary>
+    [NotClientImplementable]
     public interface IStyledPropertyMetadata
     {
         /// <summary>

src/Avalonia.Base/Input/IAccessKeyHandler.cs

@@ -1,8 +1,11 @@
+using Avalonia.Metadata;
+
 namespace Avalonia.Input
 {
     /// <summary>
     /// Defines the interface for classes that handle access keys for a window.
     /// </summary>
+    [Unstable]
     public interface IAccessKeyHandler
     {
         /// <summary>

src/Avalonia.Base/Input/IFocusManager.cs

@@ -1,8 +1,11 @@
+using Avalonia.Metadata;
+
 namespace Avalonia.Input
 {
     /// <summary>
     /// Manages focus for the application.
     /// </summary>
+    [NotClientImplementable]
     public interface IFocusManager
     {
         /// <summary>

src/Avalonia.Base/Input/IInputDevice.cs

@@ -1,7 +1,9 @@
 using Avalonia.Input.Raw;
+using Avalonia.Metadata;
 
 namespace Avalonia.Input
 {
+    [NotClientImplementable]
     public interface IInputDevice
     {
         /// <summary>

src/Avalonia.Base/Input/IInputElement.cs

@@ -1,6 +1,7 @@
 using System;
 using System.Collections.Generic;
 using Avalonia.Interactivity;
+using Avalonia.Metadata;
 using Avalonia.VisualTree;
 
 #nullable enable
@@ -10,6 +11,7 @@ namespace Avalonia.Input
     /// <summary>
     /// Defines input-related functionality for a control.
     /// </summary>
+    [NotClientImplementable]
     public interface IInputElement : IInteractive, IVisual
     {
         /// <summary>

src/Avalonia.Base/Input/IInputManager.cs

@@ -1,5 +1,6 @@
 using System;
 using Avalonia.Input.Raw;
+using Avalonia.Metadata;
 
 namespace Avalonia.Input
 {
@@ -7,6 +8,7 @@ namespace Avalonia.Input
     /// Receives input from the windowing subsystem and dispatches it to interested parties
     /// for processing.
     /// </summary>
+    [NotClientImplementable]
     public interface IInputManager
     {
         /// <summary>

src/Avalonia.Base/Input/IInputRoot.cs

@@ -1,8 +1,11 @@
+using Avalonia.Metadata;
+
 namespace Avalonia.Input
 {
     /// <summary>
     /// Defines the interface for top-level input elements.
     /// </summary>
+    [NotClientImplementable]
     public interface IInputRoot : IInputElement
     {
         /// <summary>

src/Avalonia.Base/Input/IKeyboardDevice.cs

@@ -1,5 +1,6 @@
 using System;
 using System.ComponentModel;
+using Avalonia.Metadata;
 
 namespace Avalonia.Input
 {
@@ -50,6 +51,7 @@ namespace Avalonia.Input
         KeyboardMask = Alt | Control | Shift | Meta
     }
 
+    [NotClientImplementable]
     public interface IKeyboardDevice : IInputDevice, INotifyPropertyChanged
     {
         IInputElement? FocusedElement { get; }

src/Avalonia.Base/Input/IKeyboardNavigationHandler.cs

@@ -1,8 +1,11 @@
+using Avalonia.Metadata;
+
 namespace Avalonia.Input
 {
     /// <summary>
     /// Defines the interface for classes that handle keyboard navigation for a window.
     /// </summary>
+    [Unstable]
     public interface IKeyboardNavigationHandler
     {
         /// <summary>

src/Avalonia.Base/Input/IMainMenu.cs

@@ -1,5 +1,6 @@
 using System;
 using Avalonia.Interactivity;
+using Avalonia.Metadata;
 using Avalonia.VisualTree;
 
 namespace Avalonia.Input
@@ -7,6 +8,7 @@ namespace Avalonia.Input
     /// <summary>
     /// Defines the interface for a window's main menu.
     /// </summary>
+    [NotClientImplementable]
     public interface IMainMenu : IVisual
     {
         /// <summary>

src/Avalonia.Base/Input/IMouseDevice.cs

@@ -1,10 +1,12 @@
 using System;
+using Avalonia.Metadata;
 
 namespace Avalonia.Input
 {
     /// <summary>
     /// Represents a mouse device.
     /// </summary>
+    [NotClientImplementable]
     public interface IMouseDevice : IPointerDevice
     {
         /// <summary>

src/Avalonia.Base/Input/IPointer.cs

@@ -1,5 +1,8 @@
+using Avalonia.Metadata;
+
 namespace Avalonia.Input
 {
+    [NotClientImplementable]
     public interface IPointer
     {
         int Id { get; }

src/Avalonia.Base/Input/IPointerDevice.cs

@@ -1,9 +1,11 @@
 using System;
 using Avalonia.VisualTree;
 using Avalonia.Input.Raw;
+using Avalonia.Metadata;
 
 namespace Avalonia.Input
 {
+    [NotClientImplementable]
     public interface IPointerDevice : IInputDevice
     {
         /// <inheritdoc cref="IPointer.Captured" />

src/Avalonia.Base/Input/Platform/IClipboard.cs

@@ -1,7 +1,9 @@
 using System.Threading.Tasks;
+using Avalonia.Metadata;
 
 namespace Avalonia.Input.Platform
 {
+    [NotClientImplementable]
     public interface IClipboard
     {
         Task<string> GetTextAsync();

src/Avalonia.Base/Input/Platform/IPlatformDragSource.cs

@@ -1,7 +1,9 @@
 using System.Threading.Tasks;
+using Avalonia.Metadata;
 
 namespace Avalonia.Input.Platform
 {
+    [Unstable]
     public interface IPlatformDragSource
     {
         Task<DragDropEffects> DoDragDrop(PointerEventArgs triggerEvent, IDataObject data, DragDropEffects allowedEffects);

src/Avalonia.Base/Input/Raw/IDragDropDevice.cs

@@ -1,5 +1,8 @@
-namespace Avalonia.Input.Raw
+using Avalonia.Metadata;
+
+namespace Avalonia.Input.Raw
 {
+    [NotClientImplementable]
     public interface IDragDropDevice : IInputDevice
     {
     }

src/Avalonia.Base/Input/TextInput/ITextInputMethodImpl.cs

@@ -1,5 +1,8 @@
+using Avalonia.Metadata;
+
 namespace Avalonia.Input.TextInput
 {
+    [Unstable]
     public interface ITextInputMethodImpl
     {
         void SetClient(ITextInputMethodClient? client);
@@ -8,6 +11,7 @@ namespace Avalonia.Input.TextInput
         void Reset();
     }
     
+    [NotClientImplementable]
     public interface ITextInputMethodRoot : IInputRoot
     {
         ITextInputMethodImpl? InputMethod { get; }

src/Avalonia.Base/Interactivity/IInteractive.cs

@@ -1,4 +1,5 @@
 using System;
+using Avalonia.Metadata;
 
 #nullable enable
 
@@ -7,6 +8,7 @@ namespace Avalonia.Interactivity
     /// <summary>
     /// Interface for objects that raise routed events.
     /// </summary>
+    [NotClientImplementable]
     public interface IInteractive
     {
         /// <summary>

src/Avalonia.Base/Layout/ILayoutManager.cs

@@ -1,12 +1,12 @@
 using System;
-
+using Avalonia.Metadata;
-#nullable enable
 
 namespace Avalonia.Layout
 {
     /// <summary>
     /// Manages measuring and arranging of controls.
     /// </summary>
+    [NotClientImplementable]
     public interface ILayoutManager : IDisposable
     {
         /// <summary>

src/Avalonia.Base/Layout/ILayoutRoot.cs

@@ -1,8 +1,11 @@
+using Avalonia.Metadata;
+
 namespace Avalonia.Layout
 {
     /// <summary>
     /// Defines the root of a layoutable tree.
     /// </summary>
+    [NotClientImplementable]
     public interface ILayoutRoot : ILayoutable
     {
         /// <summary>

src/Avalonia.Base/Layout/ILayoutable.cs

@@ -1,12 +1,12 @@
+using Avalonia.Metadata;
 using Avalonia.VisualTree;
 
-#nullable enable
-
 namespace Avalonia.Layout
 {
     /// <summary>
     /// Defines layout-related functionality for a control.
     /// </summary>
+    [NotClientImplementable]
     public interface ILayoutable : IVisual
     {
         /// <summary>

src/Avalonia.Base/LogicalTree/ILogical.cs

@@ -1,12 +1,14 @@
 using System;
 using Avalonia.Collections;
 using Avalonia.Controls;
+using Avalonia.Metadata;
 
 namespace Avalonia.LogicalTree
 {
     /// <summary>
     /// Represents a node in the logical tree.
     /// </summary>
+    [NotClientImplementable]
     public interface ILogical
     {
         /// <summary>

src/Avalonia.Base/LogicalTree/ILogicalRoot.cs

@@ -1,8 +1,11 @@
-namespace Avalonia.LogicalTree
+using Avalonia.Metadata;
+
+namespace Avalonia.LogicalTree
 {
     /// <summary>
     /// Represents a root of a logical tree.
     /// </summary>
+    [NotClientImplementable]
     public interface ILogicalRoot : ILogical
     {
     }

src/Avalonia.Base/Media/IBrush.cs

@@ -1,4 +1,5 @@
 using System.ComponentModel;
+using Avalonia.Metadata;
 
 namespace Avalonia.Media
 {
@@ -6,6 +7,7 @@ namespace Avalonia.Media
     /// Describes how an area is painted.
     /// </summary>
     [TypeConverter(typeof(BrushConverter))]
+    [NotClientImplementable]
     public interface IBrush
     {
         /// <summary>

src/Avalonia.Base/Media/IConicGradientBrush.cs

@@ -1,8 +1,11 @@
-namespace Avalonia.Media
+using Avalonia.Metadata;
+
+namespace Avalonia.Media
 {
     /// <summary>
     /// Paints an area with a conic gradient.
     /// </summary>
+    [NotClientImplementable]
     public interface IConicGradientBrush : IGradientBrush
     {
         /// <summary>

src/Avalonia.Base/Media/IDashStyle.cs

@@ -1,10 +1,12 @@
 using System.Collections.Generic;
+using Avalonia.Metadata;
 
 namespace Avalonia.Media
 {
     /// <summary>
     /// Represents the sequence of dashes and gaps that will be applied by a <see cref="Pen"/>.
     /// </summary>
+    [NotClientImplementable]
     public interface IDashStyle
     {
         /// <summary>

src/Avalonia.Base/Media/IExperimentalAcrylicMaterial.cs

@@ -1,8 +1,11 @@
-namespace Avalonia.Media
+using Avalonia.Metadata;
+
+namespace Avalonia.Media
 {
     /// <summary>
     /// Experimental Interface for producing Acrylic-like materials.
     /// </summary>
+    [NotClientImplementable]
     public interface IExperimentalAcrylicMaterial
     {
         /// <summary>

src/Avalonia.Base/Media/IGradientBrush.cs

@@ -1,10 +1,12 @@
 using System.Collections.Generic;
+using Avalonia.Metadata;
 
 namespace Avalonia.Media
 {
     /// <summary>
     /// A brush that draws with a gradient.
     /// </summary>
+    [NotClientImplementable]
     public interface IGradientBrush : IBrush
     {
         /// <summary>

src/Avalonia.Base/Media/IGradientStop.cs

@@ -1,8 +1,11 @@
-namespace Avalonia.Media
+using Avalonia.Metadata;
+
+namespace Avalonia.Media
 {
     /// <summary>
     /// Describes the location and color of a transition point in a gradient.
     /// </summary>
+    [NotClientImplementable]
     public interface IGradientStop
     {
         /// <summary>

src/Avalonia.Base/Media/IImageBrush.cs

@@ -1,10 +1,12 @@
 using Avalonia.Media.Imaging;
+using Avalonia.Metadata;
 
 namespace Avalonia.Media
 {
     /// <summary>
     /// Paints an area with an <see cref="IBitmap"/>.
     /// </summary>
+    [NotClientImplementable]
     public interface IImageBrush : ITileBrush
     {
         /// <summary>
@@ -12,4 +14,4 @@ namespace Avalonia.Media
         /// </summary>
         IBitmap Source { get; }
     }
-}
+}

src/Avalonia.Base/Media/ILinearGradientBrush.cs

@@ -1,8 +1,11 @@
-namespace Avalonia.Media
+using Avalonia.Metadata;
+
+namespace Avalonia.Media
 {
     /// <summary>
     /// A brush that draws with a linear gradient.
     /// </summary>
+    [NotClientImplementable]
     public interface ILinearGradientBrush : IGradientBrush
     {
         /// <summary>
@@ -15,4 +18,4 @@
         /// </summary>
         RelativePoint EndPoint { get; }
     }
-}
+}

src/Avalonia.Base/Media/IMutableBrush.cs

@@ -1,10 +1,12 @@
 using System;
+using Avalonia.Metadata;
 
 namespace Avalonia.Media
 {
     /// <summary>
     /// Represents a mutable brush which can return an immutable clone of itself.
     /// </summary>
+    [NotClientImplementable]
     public interface IMutableBrush : IBrush, IAffectsRender
     {
         /// <summary>

src/Avalonia.Base/Media/IMutableExperimentalAcrylicMaterial.cs

@@ -1,8 +1,11 @@
-namespace Avalonia.Media
+using Avalonia.Metadata;
+
+namespace Avalonia.Media
 {
     /// <summary>
     /// Represents a mutable brush which can return an immutable clone of itself.
     /// </summary>
+    [NotClientImplementable]
     public interface IMutableExperimentalAcrylicMaterial : IExperimentalAcrylicMaterial, IAffectsRender
     {
         /// <summary>

src/Avalonia.Base/Media/IMutableTransform.cs

@@ -1,4 +1,5 @@
 using System;
+using Avalonia.Metadata;
 
 namespace Avalonia.Media
 {

src/Avalonia.Base/Media/IPen.cs

@@ -1,8 +1,11 @@
-namespace Avalonia.Media
+using Avalonia.Metadata;
+
+namespace Avalonia.Media
 {
     /// <summary>
     /// Describes how a stroke is drawn.
     /// </summary>
+    [NotClientImplementable]
     public interface IPen
     {
         /// <summary>

src/Avalonia.Base/Media/IRadialGradientBrush.cs

@@ -1,8 +1,11 @@
-namespace Avalonia.Media
+using Avalonia.Metadata;
+
+namespace Avalonia.Media
 {
     /// <summary>
     /// Paints an area with a radial gradient.
     /// </summary>
+    [NotClientImplementable]
     public interface IRadialGradientBrush : IGradientBrush
     {
         /// <summary>
@@ -21,4 +24,4 @@
         /// </summary>
         double Radius { get; }
     }
-}
+}

src/Avalonia.Base/Media/ISolidColorBrush.cs

@@ -1,8 +1,11 @@
+using Avalonia.Metadata;
+
 namespace Avalonia.Media
 {
     /// <summary>
     /// Fills an area with a solid color.
     /// </summary>
+    [NotClientImplementable]
     public interface ISolidColorBrush : IBrush
     {
         /// <summary>
@@ -10,4 +13,4 @@ namespace Avalonia.Media
         /// </summary>
         Color Color { get; }
     }
-}
+}

src/Avalonia.Base/Media/ITileBrush.cs

@@ -1,10 +1,12 @@
 using Avalonia.Media.Imaging;
+using Avalonia.Metadata;
 
 namespace Avalonia.Media
-{  
+{
     /// <summary>
     /// A brush which displays a repeating image.
     /// </summary>
+    [NotClientImplementable]
     public interface ITileBrush : IBrush
     {
         /// <summary>

src/Avalonia.Base/Media/IVisualBrush.cs

@@ -1,10 +1,12 @@
-using Avalonia.VisualTree;
+using Avalonia.Metadata;
+using Avalonia.VisualTree;
 
 namespace Avalonia.Media
 {
     /// <summary>
     /// Paints an area with an <see cref="IVisual"/>.
     /// </summary>
+    [NotClientImplementable]
     public interface IVisualBrush : ITileBrush
     {
         /// <summary>
@@ -12,4 +14,4 @@ namespace Avalonia.Media
         /// </summary>
         IVisual Visual { get; }
     }
-}
+}

src/Avalonia.Base/Media/Imaging/IBitmap.cs

@@ -1,5 +1,6 @@
 using System;
 using System.IO;
+using Avalonia.Metadata;
 using Avalonia.Platform;
 using Avalonia.Utilities;
 
@@ -8,6 +9,7 @@ namespace Avalonia.Media.Imaging
     /// <summary>
     /// Represents a bitmap image.
     /// </summary>
+    [NotClientImplementable]
     public interface IBitmap : IImage, IDisposable
     {
         /// <summary>

src/Avalonia.Base/Media/TextFormatting/ITextSource.cs

@@ -1,8 +1,11 @@
-namespace Avalonia.Media.TextFormatting
+using Avalonia.Metadata;
+
+namespace Avalonia.Media.TextFormatting
 {
     /// <summary>
     /// Produces <see cref="TextRun"/> objects that are used by the <see cref="TextFormatter"/>.
     /// </summary>
+    [NotClientImplementable]
     public interface ITextSource
     {
         /// <summary>

src/Avalonia.Base/Metadata/NotClientImplementableAttribute.cs

@@ -0,0 +1,17 @@
+using System;
+
+namespace Avalonia.Metadata
+{
+    /// <summary>
+    /// This interface is not intended to be implemented outside of the core Avalonia framework as
+    /// its API may change without warning.
+    /// </summary>
+    /// <remarks>
+    /// This interface is stable for consumption by a client, but should not be implemented as members
+    /// may be added to its API.
+    /// </remarks>
+    [AttributeUsage(AttributeTargets.Interface)]
+    public class NotClientImplementableAttribute : Attribute
+    {
+    }
+}

src/Avalonia.Base/Metadata/UnstableAttribute.cs

@@ -0,0 +1,12 @@
+using System;
+
+namespace Avalonia.Metadata
+{
+    /// <summary>
+    /// This API is unstable and is not covered by API compatibility guarantees between minor and
+    /// patch releases.
+    /// </summary>
+    public class UnstableAttribute : Attribute
+    {
+    }
+}

src/Avalonia.Base/Platform/IAssetLoader.cs

@@ -2,12 +2,14 @@ using System;
 using System.Collections.Generic;
 using System.IO;
 using System.Reflection;
+using Avalonia.Metadata;
 
 namespace Avalonia.Platform
 {
     /// <summary>
     /// Loads assets compiled into the application binary.
     /// </summary>
+    [Unstable]
     public interface IAssetLoader
     {
         /// <summary>

src/Avalonia.Base/Platform/IBitmapImpl.cs

@@ -1,11 +1,13 @@
 using System;
 using System.IO;
+using Avalonia.Metadata;
 
 namespace Avalonia.Platform
 {
     /// <summary>
     /// Defines the platform-specific interface for a <see cref="Avalonia.Media.Imaging.Bitmap"/>.
     /// </summary>
+    [Unstable]
     public interface IBitmapImpl : IDisposable
     {
         /// <summary>

src/Avalonia.Base/Platform/ICursorImpl.cs

@@ -1,5 +1,6 @@
 using System;
 using Avalonia.Input;
+using Avalonia.Metadata;
 
 #nullable enable
 
@@ -8,6 +9,7 @@ namespace Avalonia.Platform
     /// <summary>
     /// Represents a platform implementation of a <see cref="Cursor"/>.
     /// </summary>
+    [Unstable]
     public interface ICursorImpl : IDisposable
     {
     }

src/Avalonia.Base/Platform/IDrawingContextImpl.cs

@@ -3,12 +3,14 @@ using Avalonia.Media;
 using Avalonia.Rendering.SceneGraph;
 using Avalonia.Utilities;
 using Avalonia.Media.Imaging;
+using Avalonia.Metadata;
 
 namespace Avalonia.Platform
 {
     /// <summary>
     /// Defines the interface through which drawing occurs.
     /// </summary>
+    [Unstable]
     public interface IDrawingContextImpl : IDisposable
     {
         /// <summary>

src/Avalonia.Base/Platform/IFontManagerImpl.cs

@@ -1,9 +1,11 @@
 using System.Collections.Generic;
 using System.Globalization;
 using Avalonia.Media;
+using Avalonia.Metadata;
 
 namespace Avalonia.Platform
 {
+    [Unstable]
     public interface IFontManagerImpl
     {
         /// <summary>

src/Avalonia.Base/Platform/IGeometryImpl.cs

@@ -1,10 +1,12 @@
 using Avalonia.Media;
+using Avalonia.Metadata;
 
 namespace Avalonia.Platform
 {
     /// <summary>
     /// Defines the platform-specific interface for a <see cref="Geometry"/>.
     /// </summary>
+    [Unstable]
     public interface IGeometryImpl
     {
         /// <summary>

src/Avalonia.Base/Platform/IGlyphRunImpl.cs

@@ -1,9 +1,11 @@
 using System;
+using Avalonia.Metadata;
 
 namespace Avalonia.Platform
 {
     /// <summary>
     ///     Actual implementation of a glyph run that stores platform dependent resources.
     /// </summary>
+    [Unstable]
     public interface IGlyphRunImpl : IDisposable { }
 }

src/Avalonia.Base/Platform/IGlyphTypefaceImpl.cs

@@ -1,7 +1,9 @@
 using System;
+using Avalonia.Metadata;
 
 namespace Avalonia.Platform
 {
+    [Unstable]
     public interface IGlyphTypefaceImpl : IDisposable
     {
         /// <summary>

src/Avalonia.Base/Platform/IMacOSTopLevelPlatformHandle.cs

@@ -1,7 +1,9 @@
 using System;
+using Avalonia.Metadata;
 
 namespace Avalonia.Platform
 {
+    [Unstable]
     public interface IMacOSTopLevelPlatformHandle
     {
         IntPtr NSView { get; }

src/Avalonia.Base/Platform/IPlatformRenderInterface.cs

@@ -3,12 +3,14 @@ using System.Collections.Generic;
 using System.IO;
 using Avalonia.Media;
 using Avalonia.Media.Imaging;
+using Avalonia.Metadata;
 
 namespace Avalonia.Platform
 {
     /// <summary>
     /// Defines the main platform-specific interface for the rendering subsystem.
     /// </summary>
+    [Unstable]
     public interface IPlatformRenderInterface
     {
         /// <summary>

src/Avalonia.Base/Platform/IPlatformSettings.cs

@@ -1,7 +1,9 @@
 using System;
+using Avalonia.Metadata;
 
 namespace Avalonia.Platform
 {
+    [Unstable]
     public interface IPlatformSettings
     {
         Size DoubleClickSize { get; }

src/Avalonia.Base/Platform/IPlatformThreadingInterface.cs

@@ -1,5 +1,6 @@
 using System;
 using System.Threading;
+using Avalonia.Metadata;
 using Avalonia.Threading;
 
 namespace Avalonia.Platform
@@ -7,6 +8,7 @@ namespace Avalonia.Platform
     /// <summary>
     /// Provides platform-specific services relating to threading.
     /// </summary>
+    [Unstable]
     public interface IPlatformThreadingInterface
     {
         void RunLoop(CancellationToken cancellationToken);

src/Avalonia.Base/Platform/IRenderTargetBitmapImpl.cs

@@ -1,3 +1,4 @@
+using Avalonia.Metadata;
 
 namespace Avalonia.Platform
 {
@@ -5,6 +6,7 @@ namespace Avalonia.Platform
     /// Defines the platform-specific interface for a
     /// <see cref="Avalonia.Media.Imaging.RenderTargetBitmap"/>.
     /// </summary>
+    [Unstable]
     public interface IRenderTargetBitmapImpl : IBitmapImpl, IRenderTarget
     {
     }

src/Avalonia.Base/Platform/IRuntimePlatform.cs

@@ -1,7 +1,9 @@
 using System;
+using Avalonia.Metadata;
 
 namespace Avalonia.Platform
 {
+    [Unstable]
     public interface IRuntimePlatform
     {
         IDisposable StartSystemTimer(TimeSpan interval, Action tick);
@@ -9,6 +11,7 @@ namespace Avalonia.Platform
         IUnmanagedBlob AllocBlob(int size);
     }
 
+    [Unstable]
     public interface IUnmanagedBlob : IDisposable
     {
         IntPtr Address { get; }
@@ -17,6 +20,7 @@ namespace Avalonia.Platform
         
     }
 
+    [Unstable]
     public struct RuntimePlatformInfo
     {
         public OperatingSystemType OperatingSystem { get; set; }
@@ -29,6 +33,7 @@ namespace Avalonia.Platform
         public bool IsUnix { get; set; }
     }
 
+    [Unstable]
     public enum OperatingSystemType
     {
         Unknown,

src/Avalonia.Base/Platform/IStreamGeometryContextImpl.cs

@@ -1,8 +1,11 @@
+using Avalonia.Metadata;
+
 namespace Avalonia.Platform
 {
     /// <summary>
     /// Describes a geometry using drawing commands.
     /// </summary>
+    [Unstable]
     public interface IStreamGeometryContextImpl : IGeometryContext
     {      
     }

src/Avalonia.Base/Platform/IStreamGeometryImpl.cs

@@ -1,8 +1,11 @@
+using Avalonia.Metadata;
+
 namespace Avalonia.Platform
 {
     /// <summary>
     /// Defines the platform-specific interface for a <see cref="Avalonia.Media.StreamGeometry"/>.
     /// </summary>
+    [Unstable]
     public interface IStreamGeometryImpl : IGeometryImpl
     {
         /// <summary>

src/Avalonia.Base/Platform/ITextShaperImpl.cs

@@ -1,4 +1,5 @@
 using Avalonia.Media.TextFormatting;
+using Avalonia.Metadata;
 using Avalonia.Utilities;
 
 namespace Avalonia.Platform
@@ -6,6 +7,7 @@ namespace Avalonia.Platform
     /// <summary>
     /// An abstraction that is used produce shaped text.
     /// </summary>
+    [Unstable]
     public interface ITextShaperImpl
     {
         /// <summary>

src/Avalonia.Base/Platform/ITransformedGeometryImpl.cs

@@ -1,4 +1,6 @@
-namespace Avalonia.Platform
+using Avalonia.Metadata;
+
+namespace Avalonia.Platform
 {
     /// <summary>
     /// Represents a geometry with a transform applied.
@@ -7,6 +9,7 @@
     /// An <see cref="ITransformedGeometryImpl"/> transforms a geometry without transforming its
     /// stroke thickness.
     /// </remarks>
+    [Unstable]
     public interface ITransformedGeometryImpl : IGeometryImpl
     {
         /// <summary>

src/Avalonia.Base/Platform/IWriteableBitmapImpl.cs

@@ -1,8 +1,11 @@
-namespace Avalonia.Platform
+using Avalonia.Metadata;
+
+namespace Avalonia.Platform
 {
     /// <summary>
     /// Defines the platform-specific interface for a <see cref="Avalonia.Media.Imaging.WriteableBitmap"/>.
     /// </summary>
+    [Unstable]
     public interface IWriteableBitmapImpl : IBitmapImpl
     {
         ILockedFramebuffer Lock();

src/Avalonia.Base/Platform/Interop/IDynamicLibraryLoader.cs

@@ -1,7 +1,9 @@
 using System;
+using Avalonia.Metadata;
 
 namespace Avalonia.Platform.Interop
 {
+    [Unstable]
     public interface IDynamicLibraryLoader
     {
         IntPtr LoadLibrary(string dll);

src/Avalonia.Base/Rendering/IDeferredRendererLock.cs

@@ -1,7 +1,9 @@
 using System;
+using Avalonia.Metadata;
 
 namespace Avalonia.Rendering
 {
+    [Unstable]
     public interface IDeferredRendererLock
     {
         IDisposable? TryLock();

src/Avalonia.Base/Rendering/IRenderLoop.cs

@@ -1,4 +1,6 @@
-namespace Avalonia.Rendering
+using Avalonia.Metadata;
+
+namespace Avalonia.Rendering
 {
     /// <summary>
     /// The application render loop.
@@ -7,6 +9,7 @@
     /// The render loop is responsible for advancing the animation timer and updating the scene
     /// graph for visible windows.
     /// </remarks>
+    [NotClientImplementable]
     public interface IRenderLoop
     {
         /// <summary>

src/Avalonia.Base/Rendering/IRenderRoot.cs

@@ -1,3 +1,4 @@
+using Avalonia.Metadata;
 using Avalonia.Platform;
 using Avalonia.VisualTree;
 
@@ -6,6 +7,7 @@ namespace Avalonia.Rendering
     /// <summary>
     /// Represents the root of a renderable tree.
     /// </summary>
+    [NotClientImplementable]
     public interface IRenderRoot : IVisual
     {
         /// <summary>

src/Avalonia.Base/Rendering/IRenderTimer.cs

@@ -1,11 +1,13 @@
 using System;
 using System.Threading.Tasks;
+using Avalonia.Metadata;
 
 namespace Avalonia.Rendering
 {
     /// <summary>
     /// Defines the interface implemented by an application render timer.
     /// </summary>
+    [NotClientImplementable]
     public interface IRenderTimer
     {
         /// <summary>

src/Avalonia.Base/Rendering/IVisualBrushInitialize.cs

@@ -1,4 +1,5 @@
 using Avalonia.Media;
+using Avalonia.Metadata;
 
 namespace Avalonia.Rendering
 {
@@ -6,6 +7,7 @@ namespace Avalonia.Rendering
     /// Internal interface for initializing controls that are to be used as the visual in a
     /// <see cref="VisualBrush"/>.
     /// </summary>
+    [Unstable]
     public interface IVisualBrushInitialize
     {
         /// <summary>

src/Avalonia.Base/Rendering/IVisualBrushRenderer.cs

@@ -1,4 +1,5 @@
 using Avalonia.Media;
+using Avalonia.Metadata;
 using Avalonia.Platform;
 
 namespace Avalonia.Rendering
@@ -6,6 +7,7 @@ namespace Avalonia.Rendering
     /// <summary>
     /// Defines a renderer used to render a visual brush to a bitmap.
     /// </summary>
+    [Unstable]
     public interface IVisualBrushRenderer
     {
         /// <summary>

src/Avalonia.Base/Styling/Activators/IStyleActivator.cs

@@ -1,6 +1,5 @@
-#nullable enable
+using System;
-
+using Avalonia.Metadata;
-using System;
 
 namespace Avalonia.Styling.Activators
 {
@@ -16,6 +15,7 @@ namespace Avalonia.Styling.Activators
     /// - The subscription can have a tag associated with it, allowing a subscriber to index
     ///   into a list of subscriptions without having to allocate additional objects.
     /// </remarks>
+    [Unstable]
     public interface IStyleActivator : IDisposable
     {
         /// <summary>

src/Avalonia.Base/Styling/Activators/IStyleActivatorSink.cs

@@ -1,10 +1,11 @@
-#nullable enable
+using Avalonia.Metadata;
 
 namespace Avalonia.Styling.Activators
 {
     /// <summary>
     /// Receives notifications from an <see cref="IStyleActivator"/>.
     /// </summary>
+    [Unstable]
     public interface IStyleActivatorSink
     {
         /// <summary>

src/Avalonia.Base/Styling/IGlobalStyles.cs

@@ -1,13 +1,13 @@
 using System;
 using System.Collections.Generic;
-
+using Avalonia.Metadata;
-#nullable enable
 
 namespace Avalonia.Styling
 {
     /// <summary>
     /// Defines the style host that provides styles global to the application.
     /// </summary>
+    [NotClientImplementable]
     public interface IGlobalStyles : IStyleHost
     {
         /// <summary>

src/Avalonia.Base/Styling/ISetter.cs

@@ -1,12 +1,12 @@
 using System;
-
+using Avalonia.Metadata;
-#nullable enable
 
 namespace Avalonia.Styling
 {
     /// <summary>
     /// Represents a setter for a <see cref="Style"/>.
     /// </summary>
+    [NotClientImplementable]
     public interface ISetter
     {
         /// <summary>

src/Avalonia.Base/Styling/ISetterInstance.cs

@@ -1,12 +1,12 @@
-#nullable enable
+using System;
-
+using Avalonia.Metadata;
-using System;
 
 namespace Avalonia.Styling
 {
     /// <summary>
     /// Represents a setter that has been instanced on a control.
     /// </summary>
+    [Unstable]
     public interface ISetterInstance : IDisposable
     {
         /// <summary>

src/Avalonia.Base/Styling/IStyle.cs

@@ -1,13 +1,12 @@
 using System.Collections.Generic;
-using Avalonia.Controls;
+using Avalonia.Metadata;
-
-#nullable enable
 
 namespace Avalonia.Styling
 {
     /// <summary>
     /// Defines the interface for styles.
     /// </summary>
+    [NotClientImplementable]
     public interface IStyle
     {
         /// <summary>

src/Avalonia.Base/Styling/IStyleHost.cs

@@ -1,5 +1,6 @@
 
 using System.Collections.Generic;
+using Avalonia.Metadata;
 
 #nullable enable
 
@@ -8,6 +9,7 @@ namespace Avalonia.Styling
     /// <summary>
     /// Defines an element that has a <see cref="Styles"/> collection.
     /// </summary>
+    [NotClientImplementable]
     public interface IStyleHost
     {
         /// <summary>

src/Avalonia.Base/Styling/IStyleInstance.cs

@@ -1,12 +1,12 @@
 using System;
-
+using Avalonia.Metadata;
-#nullable enable
 
 namespace Avalonia.Styling
 {
     /// <summary>
     /// Represents a style that has been instanced on a control.
     /// </summary>
+    [Unstable]
     public interface IStyleInstance : IDisposable
     {
         /// <summary>

src/Avalonia.Base/Styling/IStyleable.cs

@@ -1,6 +1,7 @@
 using System;
 using System.Collections.Generic;
 using Avalonia.Collections;
+using Avalonia.Metadata;
 
 #nullable enable
 
@@ -9,6 +10,7 @@ namespace Avalonia.Styling
     /// <summary>
     /// Interface for styleable elements.
     /// </summary>
+    [NotClientImplementable]
     public interface IStyleable : IAvaloniaObject, INamed
     {
         /// <summary>

src/Avalonia.Base/Styling/ITemplatedControl.cs

@@ -1,6 +1,8 @@
+using Avalonia.Metadata;
 
 namespace Avalonia.Styling
 {
+    [NotClientImplementable]
     public interface ITemplatedControl : IAvaloniaObject
     {
     }

src/Avalonia.Base/VisualTree/IVisual.cs

@@ -1,10 +1,9 @@
 using System;
 using Avalonia.Collections;
 using Avalonia.Media;
+using Avalonia.Metadata;
 using Avalonia.Rendering;
 
-#nullable enable
-
 namespace Avalonia.VisualTree
 {
     /// <summary>
@@ -18,6 +17,7 @@ namespace Avalonia.VisualTree
     /// implemented by <see cref="Visual"/>. It should not be necessary to implement it
     /// anywhere else.
     /// </remarks>
+    [NotClientImplementable]
     public interface IVisual
     {
         /// <summary>