dotnet-techne-csharp-api-design

# Public API Design and Compatibility ## When to Use This Skill Use this skill when: - Designing public APIs for NuGet packages or libraries - Making changes to existing public APIs - Planning wire format changes for distributed systems - Implementing versioning strategies - Reviewing pull requests for breaking changes --- ## The Three Types of Compatibility | Type | Definition | Scope | |------|------------|-------| | **API/Source** | Code compiles against newer version | Public method signatures, types | | **Binary** | Compiled code runs against newer version | Assembly layout, method tokens | | **Wire** | Serialized data readable by other versions | Network protocols, persistence formats | Breaking any of these creates upgrade friction for users. --- ## Extend-Only Design The foundation of stable APIs: **never remove or modify, only extend**. ### Three Pillars 1. **Previous functionality is immutable** - Once released, behavior and signatures are locked 2. **New functionality through new constructs** - Add overloads, new types, opt-in features 3. **Removal only after deprecation period** - Years, not releases ### Benefits - Old code continues working in new versions - New and old pathways coexist - Upgrades are non-breaking by default - Users upgrade on their schedule **Resources:** - [Extend-Only Design](https://aaronstannard.com/extend-only-design/) - [OSS Compatibility Standards](https://aaronstannard.com/oss-compatibility-standards/) --- ## API Change G...