I like library providers that can provide mechanical upgrade instructions. For example:

model.adjust(x,1,y) is now model.single(Adjustment.Foo, x).with_attribute(y)

Or whatever. Then people can go through your instructions find-and-replacing the changes, or even better, have an automated tool do it.

Also you pay some of the maintenance burden by writing all this documentation, so you have a some stake in keeping the changes minimal.