[vtk-developers] policy on VTK API changes

[Randall Hand]

I wholeheartedly agree. I've run into similar problems with the recent 
changes to the filters that removed the "SetInputScalars" in favor of the 
more generic "SetInputArrayToProcess", and it's mostly undocumented syntax. 
and again with the vtkKitwareContourFilter vanished, with it's functionality 
absorbed into the generic vtkContourFilter, but nothing was said about this 
on the website, the TWiki (that i've been able to find), or the mailing 
lists.

It would be great if these changes were all documented somewhere in a "
VTK4.4 to CVS Changes" document. Even better, it would be great if such 
changes were "phased in", eg Make SetInputScalars simply call 
SetInputArrayToProcess, and print a "Warning: This method is deprecated, 
please use SetInputArraytoProcess with the following arguments: blah blah". 
It makes it really hard to use VTK when the syntax & rules change to 
incompatible forms so often.

On 6/2/05, Michael Halle <mhalle at bwh.harvard.edu> wrote:
> 
> Hello,
> 
> I've recently been developing and testing some code
> using the CVS version of VTK. In my testing, I found
> that one of the method names for a class I wrote,
> vtkLightKit, had been changed for "for naming
> consistency" as the CVS logs say.
> 
> The details, which aren't incredibly important,
> involve the naming of lights. LightKit has a key light,
> a fill light, several back lights, and a headlight. When
> I wrote the module, I called the lights KeyLight, FillLight,
> BackLight, and Headlight. Headlight wasn't HeadLight
> because "headlight" is an English word, and BackLight wasn't
> Backlight because several discrete "back lights" form the
> "backlighting" of the scene. Was this the best choice?
> Certainly debatable, but I was the author and I made the
> choice based on at least some rational thought.
> 
> Recently, Mathieu Malaterre did some code cleaning and
> changed Headlight to HeadLight for consistency. While
> I understand the decision to do so (I love consistent
> code names too, and I'm not necessarily wedded to
> my way anyway), this is an API change based on aesthetics
> that breaks compatibility with existing code.
> vtkLightKit isn't the most widely used module, but it has
> been in vtk since 4.0, and this change wasn't
> really required for anything other than aesthetics.
> 
> As potentially important as these kind of changes are for
> the usability of the system, it's really important to keep
> in mind that these kind of changes break other people's code.
> There are various ways to deal with it (backwards compatibility
> synonyms, for example), but at the very least it would
> be useful for outside developers to have a list of these
> kind of changes to help with the porting process from one
> release to the next.
> 
> Again, let me stress that the bigger issue is far more important
> to me that this relatively minor example of it.
> 
> Could Kitware establish and promote a consistent policy
> on API changes?
> 
> Thanks.
> 
> Michael Halle
> mhalle at bwh.harvard.edu
> 
> 
> _______________________________________________
> vtk-developers mailing list
> vtk-developers at vtk.org
> http://www.vtk.org/mailman/listinfo/vtk-developers
> 



-- 
Randall Hand
http://www.yeraze.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://public.kitware.com/pipermail/vtk-developers/attachments/20050602/0830d7f4/attachment.html>