Saturday, April 09, 2005 - Posts

What's a breaking change ... and what's not?

When updating an assembly from one version to the next, it can be difficult to assess which changes will affect clients of the assembly. Generally referred to as a “breaking change”, altering an assembly can have dangerous side-affects which both irritate, and compound problems for users. At their minimum, breaking changes are problematic and frustrating. At their extreme, they mean that an application built upon the broken assembly will no longer function, therefore tying that consumer to your older assembly, meaning a) the client loses any and all benefits from using the new assembly, and b) you lose income from providing the newer assembly, which clearly is not what the client wanted.

Effectively, the decision to break an assembly paints your client into a corner: redesign their own Application Programming Interfaces (APIs) to take advantage of the new assembly, or be stuck with the older assembly. One choice is costly to them, the other is costly to you. Neither is optimal.

It is useful therefore, to define what changes you deem ‘acceptable’ for your assembly. While all considerably breaking changes should be addressed on their own merits, a general framework for helping make the decision can only be good. [Via Brad Abrams]

If you are about to make a code change, and are uncertain if the change is breaking then you should definitely read this document. Especially if you're working in an environment where you don't control all client code this can be considered as good guidance!

with 4 Comments