[vtk-developers] policy on VTK API changes

[Michael Halle]

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