Backwards Compatibility

[uckelman]

@rk

Usually, a module is incompatible because it uses custom Java code, but the
underlying VASSAL code has changed between versions. We will try to do a
better job in the future to make the code backward compatible.

Fortunately, most of the custom Java code in use is for features that have
since been incorporated into the core VASSAL engine, such as the
TurnTracker. In that case, making the module compatible is just as simple
as deleting the custom component and reconstructing it using the standard
component in the new VASSAL version.

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

<VASSAL.build.module.map.Zoomer version="1">

the contents of which would be interepreted differently from

<VASSAL.build.module.map.Zoomer version="2">

or

<VASSAL.build.module.map.Zoomer> (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?)

[Brent_Easton]

Joel,

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.

Regards,
Brent.

[rk1]

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.

rk

Post generated using Mail2Forum (mail2forum.com)

[uckelman]

Thus spake “Rodney Kinney”:

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.

rk

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.

–
J.

---

Messages mailing list
Messages@forums.vassalengine.org
forums.vassalengine.org/mailman/ … engine.org

Post generated using Mail2Forum (mail2forum.com)