api-design

To evolve a public API without breaking existing library users, practice extend-only design by never removing or modifying public members. Grow the API surface additively by adding new method overloads or introducing entirely new types.

Extend-only API design preserves backward compatibility by enforcing strict non-removal of existing public members. It ensures old clients can interact with new data formats and compiled surfaces by applying additive changes through overloads.

To deprecate public API members during migration, establish clear deprecation paths and documentation. Keep old members intact to preserve compatibility while guiding users toward new overloads or replacement types.

Yes, extend-only design works for distributed systems by maintaining wire and binary compatibility. It ensures old clients can safely read new data formats without encountering removed or modified compiled surfaces.

The best way to add features to a NuGet package without breaking binary compatibility is to extend the public API surface additively. Introduce new types or method overloads instead of renaming or removing existing members.