Backwards Compatibility

Since we’re not too terribly far from a 3.1.0 release, maybe the future is
now? I’d like to start a discussion about what exactly we intend to do w/r/t
backwards compatibility.

I see two areas in which there’s a backwards compatibility issue: custom
classes, and deprecated properties.

For custom classes: We’re reliant on module maintainers to act to update
classes which stop working. Its going to be difficult for us to prevent
custom class breakage, since the nature of VASSAL and Java (especially
reflection) makes it possible to modify the innards of VASSAL in ways that
we can’t possibly anticipate. The TurnTracker is rather unique, in the
sense that we knew it was a popular custom package, and then went ahead
and clobbered it anyway. (I’m not saying this was a bad decision, just
that we didn’t communicate what we were doing very well.) But in general
we’re probably not going to know, nor can we be expected to know, that
we’re doing something which will break custom code. This problem strikes
me as a social engineering one—we need to motivate module designers to
keep their modules up-to-date. I don’t know how best to do this.

What worries me more is the use of methods we’ve deprecated in custom code.
Here I think there’s a technical solution: When we deprecate methods, we
could add a call to raise a warning dialog alerting the user that a
deprecated method has been called, and that the module should be updated.
(This dialog could be set not to show again, of course. The point is to
notify, not to annoy.)

For deprecated properties: When I rewrote the Zoomer to handle lists of
zoom levels and to zoom to greater than 1:1, I found that I both needed
to add new properties to the Zoomer and deprecate the use of a few old
ones. The new Zoomer is still able to read the old properties, but will
not write them. Since the old Zoomer cannot read the new properties,
this means that a module saved with the new Zoomer but loaded with the
old one won’t have exactly the same list of zoom levels. For something
like the Zoomer, this is not much of a problem, but I could see this
sort of thing becoming a problem eventually.

Some software tracks version numbers of saved data in a way that is
more fine-grained than we do. I could imagine having getAttribute()
and setAttribute() which take a version number as an argument, and
do the right thing depending on the version number given. That, or
somehow rolling a version number as an attribute into individual
XML elements, so, you could have a

< version="1">

the contents of which would be interepreted differently from

< version="2">


<> (without a version attribute)

which would be interpreted as predating anything versioned.

I don’t know what a good way to handle this sort of thing is, because
I can foresee this generating a lot of code. Maybe the right way to
do this is to encapsulate all of this into a converter class? I wonder
how programs which can read all of the old versions of their file formats
do it without becoming buried in special-case code? (I haven’t looked
at Word in quite a while—and I would never hold it up as a model of
anything positive—but I seem to remember that it can read files from
every old version of Word, and even write files using the old file formats.
I wonder if they can do that without having a mountain of code?)


On the Custom Code subject, I am hoping that my Plugins work will make it less likely that custom code will break. It will provide a standard interface for custom code to be added to/integrated into modules that should be more robust the current way which every custom component for itself.

The problem with the Turn Tracker was actually the way the Turn tracker was added to the module, rather than with anything the turntracker was doing once the component was built.

It would be good if this could get into a release soon. It’s in swampwallaby-merge@2787.


Being backward compatible with module buildFiles is relatively easy. There are quite a few components that work like your Zoomer, reading new+old attributes but only writing the new ones.

The real problem is with custom code, where the code may refer to protected fields (in particular) that are removed or renamed in a later version. The only solution really is to simply never do that. Methods are easier to deal with because you can mark them as deprecated and change their implementation. I’ve seen projects go so far as to never declare protected fields and instead use private fields with protected get/set methods. That makes it easier to evolve the code, but it’s a lot of work up front.


Post generated using Mail2Forum (

Thus spake “Rodney Kinney”:

I tend to favor letting protected fields be use-at-your-own-risk. They’re
too tied to implementation details to be something that you should rely
on in the long run, but on the other hand, it’s unfriendly to module
designers to make fields which they might want to twiddle private.


Messages mailing list …

Post generated using Mail2Forum (