Avalonia/docs/api-compat.md

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 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 parameter with nuke
• Fallback: When not specified, uses the version defined in SharedVersion.props

Additional Resources

• API Validation Tool Implementation - Pull request that introduced this feature