Developer Documentation (#19131)

* Started improving dev docs.

* Ported "Debugging XAML compiler" from wiki.

* Ported porting tips from wiki.

* Ported release process from wiki.

* Ported "macOS Development" from docs site.

From https://docs.avaloniaui.net/docs/guides/platforms/macos-development

* Fix quotes.

Documentation/api-compat.md

@@ -0,0 +1,32 @@
+# API Compatibility
+
+Avalonia maintains strict **source and binary compatibility** within major versions. Automated API compatibility checks run on every CI build to enforce this policy—builds will fail if breaking changes are detected.
+
+## When Breaking Changes Are Permitted
+
+Breaking changes are only acceptable under these specific circumstances and **must be approved** by the Avalonia code team:
+
+- **Major version targeting**: When `master` branch is targeting a new major version
+- **Accidental public APIs**: When code was unintentionally exposed as a public API and is unlikely to have external dependencies
+- **Experimental features**: When the API is explicitly marked as unstable or experimental
+
+## Handling Approved Breaking Changes
+
+When a breaking change is approved, you can bypass CI validation using an API suppression file:
+
+1. **Generate suppression file**: Run `nuke --update-api-suppression true`
+2. **Commit changes**: Commit the [updated suppression file](../api/) in a separate commit
+
+> **Note**: The suppression file should only be updated after the breaking change has been reviewed and approved.
+
+## Baseline Version Configuration
+
+API changes are validated against a **baseline version**—the reference point for compatibility checks.
+
+- **Default behavior**: Uses the current major version (e.g., for version 11.0.5, baseline is 11.0.0)
+- **Custom baseline**: Override using the [`api-baseline`](https://github.com/AvaloniaUI/Avalonia/blob/56d94d64b9aa6f16200be39b3bcb17f03325b7f9/nukebuild/BuildParameters.cs#L27) parameter with `nuke`
+- **Fallback**: When not specified, uses the version defined in [`SharedVersion.props`](https://github.com/AvaloniaUI/Avalonia/blob/56d94d64b9aa6f16200be39b3bcb17f03325b7f9/build/SharedVersion.props#L6)
+
+## Additional Resources
+
+- [API Validation Tool Implementation](https://github.com/AvaloniaUI/Avalonia/pull/12072) - Pull request that introduced this feature

Documentation/debug-xaml-compiler.md

@@ -0,0 +1,15 @@
+# Debugging the XAML Compiler
+
+The Avalonia XAML compiler can be debugged by setting an MSBuild property which triggers a debugger launch during compilation. This allows you to step through the XAML compilation process and troubleshoot issues.
+
+To enable XAML compiler debugging, set the `AvaloniaXamlIlDebuggerLaunch` MSBuild property to `true` in your project file:
+
+```xml
+<PropertyGroup>
+  <AvaloniaXamlIlDebuggerLaunch>true</AvaloniaXamlIlDebuggerLaunch>
+</PropertyGroup>
+```
+
+When this property is enabled, the XAML compiler will call `Debugger.Launch()` on startup, which prompts you to attach a debugger to the compiler process.
+
+If you're working with the Sandbox project in the Avalonia repository, you can enable debugging by simply uncommenting the property line in the [project file](https://github.com/AvaloniaUI/Avalonia/blob/56d94d64b9aa6f16200be39b3bcb17f03325b7f9/samples/Sandbox/Sandbox.csproj#L8).

Documentation/index.md

@@ -0,0 +1,19 @@
+# Avalonia Developer Documentation
+
+This documentation covers Avalonia framework development. For user documentation on how to use Avalonia, visit https://docs.avaloniaui.net/.
+
+## Getting Started
+
+- [Building Avalonia](build.md) describes how to build Avalonia from source
+- You should read the [Contributing guidelines](../CONTRIBUTING.md) before you start
+- We have a [Code of Conduct](../CODE_OF_CONDUCT.md)
+
+## Development
+
+- [Debugging the XAML Compiler](debug-xaml-compiler.md)
+- [Porting Code from 3rd Party Sources](porting-code-from-3rd-party-sources.md)
+
+## Releases
+
+- [API Compatibility](api-compat.md) describes the API compatibility guarantees provided by Avalonia, and exceptions to these guarantees
+- Our [Release Process](release.md) describes the process for creating a new Avalonia release

Documentation/macos-native.md

@@ -0,0 +1,71 @@
+# macOS Native Code
+
+The macOS platform backend has a native component, written in objective-c and located in [`native/Avalonia.Native/src/OSX`](../native/Avalonia.Native/src/OSX/). To work on this code, open the [`Avalonia.Native.OSX.xcodeproj`](../native/Avalonia.Native/src/OSX/Avalonia.Native.OSX.xcodeproj)project in Xcode.
+
+Changes to the native portion of the code can be recompiled in two ways:
+
+1. Using the [`build.sh`](build.md#build-native-libraries-macos-only) script: this has the downside that it will trigger a full recompile of Avalonia
+2. Using `AvaloniaNativeLibraryPath` described below
+
+## Using `AvaloniaNativeLibraryPath `
+
+When you make changes in Xcode and recompile using Cmd+B, the binary will be compiled to a location that can be seen under "Products":
+
+![How to find the product path in Xcode](images/xcode-product-path.png)
+
+To use this build in Avalonia, one can specifiy the path by using `AvaloniaNativePlatformOptions.AvaloniaNativeLibraryPath` in an application's AppBuilder:
+
+```csharp
+public static AppBuilder BuildAvaloniaApp() =>
+    AppBuilder.Configure<App>()
+        .UsePlatformDetect()
+        .With(new AvaloniaNativePlatformOptions
+    { 
+        AvaloniaNativeLibraryPath = "[Path to your dylib]", 
+    })
+```
+
+# Bundling Development Code
+
+In certain situations you need to run an Avalonia sample application as an app bundle. One of these situations is testing macOS Accessibility - Xcode's Accessibility Inspector fails to recognise the application otherwise. To facilitate this, the [`IntegrationTestApp`](../samples/IntegrationTestApp/) has a [`bundle.sh`](../samples/IntegrationTestApp/bundle.sh) script which can be run to create a bundle of that application.
+
+Alteratively, if you need to bundle another project, another solution is to change the sample's output path to resemble an app bundle. You can do this by modifying the output path in the csproj, e.g.:
+
+```xml
+<OutputPath>bin\$(Configuration)\$(Platform)\ControlCatalog.NetCore.app/Contents/MacOS</OutputPath>
+<AppendTargetFrameworkToOutputPath>false</AppendTargetFrameworkToOutputPath>
+<UseAppHost>true</UseAppHost>
+```
+
+And in the Contents output directory place a valid `Info.plist` file. An example for ControlCatalog.NetCore is:
+
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+  <dict>
+    <key>CFBundleName</key>
+    <string>ControlCatalog.NetCore</string>
+    <key>CFBundleDisplayName</key>
+    <string>ControlCatalog.NetCore</string>
+    <key>CFBundleIdentifier</key>
+    <string>ControlCatalog.NetCore</string>
+    <key>CFBundleVersion</key>
+    <string>0.10.999</string>
+    <key>CFBundlePackageType</key>
+    <string>AAPL</string>
+    <key>CFBundleSignature</key>
+    <string>????</string>
+    <key>CFBundleExecutable</key>
+    <string>ControlCatalog.NetCore</string>
+    <key>CFBundleIconFile</key>
+    <string>ControlCatalog.NetCore.icns</string>
+    <key>CFBundleShortVersionString</key>
+    <string>0.1</string>
+    <key>NSPrincipalClass</key>
+    <string>NSApplication</string>
+    <key>NSHighResolutionCapable</key>
+    <true />
+  </dict>
+</plist>
+```

Documentation/porting-code-from-3rd-party-sources.md

@@ -0,0 +1,12 @@
+# Porting Code from 3rd Party Sources
+
+When porting code or adapting code from other projects with a MIT compatible license, the source file must contain appropriate license headers. For example when porting code from WPF the header should contain:
+
+```
+// This source file is adapted from the Windows Presentation Foundation project. 
+// (https://github.com/dotnet/wpf/) 
+// 
+// Licensed to The Avalonia Project under MIT License, courtesy of The .NET Foundation.
+```
+
+If the file is a port of a specific commit of file from a 3rd party source, then consider including a permalink to the source file.

Documentation/release.md

@@ -0,0 +1,30 @@
+# Release Process
+
+This document describes the process for creating a new Avalonia release
+
+## Backports
+
+- Go through PRs with "backport-candidate-*" tags, make sure this list makes sense
+- Checkout https://github.com/grokys/avalonia-backport tool from the source code, get github api token
+- Checkout stable release branch, like `release/11.0`
+- Run backport cherry-picking process to the stable release branch
+- Test if everything builds and tests are passing
+- Test nightly builds of Avalonia
+- Run labeling process (automatically replace "backport-candidate" with "backported" tags) and generate changelog
+
+## Release
+
+- Create a branch named e.g. `release/11.0.9` for the specific minor version
+- Update the version number in the file [SharedVersion.props](../build/SharedVersion.props), e.g. `<Version>11.0.9</Version>`
+- Add a tag for this version, e.g. `git tag 11.0.9`
+- Push the release branch and the tag.
+- Wait for azure pipelines to finish the build. Nightly build with 11.0.9 version should be released soon after.
+- Using the nightly build run a due diligence test to make sure you're happy with the package.
+- On azure pipelines, on the release for your release branch `release/11.0.9` click on the badge for "Nuget Release"
+- Click deploy
+- Make a release on Github releases
+- Press "Auto-generate changelog", so GitHub will append information about new contributors
+- Replace changelog with one generated by avalonia-backport tool. Enable discussion for the specific release
+- Review the release information and publish.
+- Update the dotnet templates, visual studio templates.
+- Announce on telegram (RU and EN), twitter, etc