Hi Jerome, I have been thinking about how we could manage API changes and the related pain better.
I think the best way would be to start using the @deprecated and setting a removal deadline by naming a future release. Here is a good synopsis of the annotation (picked up from a cached Google result for http://www.unf.edu/~kmartin/tutorial/java/javaOO/annotations.html @Deprecated—the @Deprecated annotation indicates that the marked element is deprecated and should no longer be used. The compiler generates a warning whenever a program uses a method, class, or field with the @Deprecated annotation. When an element is deprecated, it should also be documented using the Javadoc @deprecated tag, as shown in the following example. The use of the "@" symbol in both Javadoc comments and in annotations is not coincidental—they are related conceptually. Also, note that the Javadoc tag starts with a lowercase "d" and the annotation starts with an uppercase "D". /** * @deprecated * explanation of why it was deprecated. Alternative implementation and that it would be removed in release b20 */ @Deprecated static void deprecatedMethod() { } } I changed the example a bit by adding this part "Alternative implementation and that it would be removed in release b20". +ves 1. It gives the developers out there some breathing space to change things around and yet leverage bug fixes, enhancements etc fairly instantaneously. They have a well documented change to the API and know the alternative and the deadline by when they have to be finished. 2. The deprecated methods and classes can be removed fairly quickly from the release usually by the next release and no one can complain that they weren't informed. -ves 1. Committers have to do more legwork. But it is easier for a Commiter with a good IDE to refactor things than for a developer trying to deal with missing methods and classes! So let us take an example renaming Handler to Finder 1. Create a copy of Handler to Finder. 2. Search for handler usages … found someMethod(Handler handler) create someMethod(Finder finder) and deprecate the older one, point to the alternative and removed by release xyz. And so on. 3. Deprecate Handler and point to Finder. Of course this might be easier said than done! Any thoughts? Cheers Piyush
