[Insight-developers] API Changes in itkSpatialObject

[Lorensen, William E (GE, Research)]

Folks,

I've been working on a draft policy for API Backward Compatibility for Insight Consortium software. It's just its draft form now.

The basic principle of this policy is that once an API appears in an official release, it cannot be removed.

API's can change if:
1. The compiler, if possible, can warn the user about the deprecated API. Some compilers show line numbers where the deprecated API is being used.
2. At run-time, deprecated API's report how to change code from the old API to the new API.
3. Documentation in the deprecated code clearly informs the user how to move the code from the old API to the new API.

Section 3.6 of the draft covers Method Signature Changes:
Once appearing in an official release, changes to a public or protected method 's signature are not permitted. Changes can be made to private methods since these are not accessible outside the class.

The rationale is: Changes to a method's signature will cause compilation errors in user code that accesses the method. The compiler error cannot specifically contain corrective action.

The workaround is: A new method should be added with the new signature. If only the method's parameters are changing, then both the old and new methods may be able to co-exist. If the return type of the new method is different from the return type of the old signature, then a new method name should be created. If the ISC supported compilers cannot compile the method with both signatures, then new signature must use a new method name.

--------------------
Unfortunately, the method changed in SpatialObject is a public method that cannot co-exist with the old API so there is not a mechanism other than code documentation, e-mail, etc. to notify the user. A new method name could solve the issue, but it is not clear what that name should be.

The current PDF of the draft is at:
http://insightsoftwareconsortium.org/wiki/index.php/Administration-BackwardCompatibility

This draft has not been reviewed by other ISC members and has not yet been adopted by the ISC.

Bill