Hi Pyiush, Thanks for the precise proposition, I like the idea very much. I propose to adopt this new convention after beta 19 (which is too advanced in term of refactoring to allow this). This is also compatible with our roadmap which should lead us into a 1.0 RC cycle after beta 20.
Best regards, Jerome > -----Message d'origine----- > De : Piyush Purang [mailto:[EMAIL PROTECTED] > Envoyé : lundi 9 octobre 2006 11:48 > À : [email protected] > Objet : New releases and API changes > > 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 > > > @Deprecatedthe @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 coincidentalthey 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 > >
