Re: A rant about backward-incompatible changes

[Paul K <paul@...>]

Hi Simon,

I'm largely in the same boat as I maintain several Lua modules that
need to work across Lua 5.1, 5.2, and 5.3 versions (including those
compiled with non-default options). Having said that, I have a
different perspective on Lua incompatibility as some of the breakage
is expected and given the slow pace of Lua releases is not too
difficult to handle.

> One more thing: from an application writer's perspective, having
> backward-compatibility options available in luaconf.h makes things a
> whole lot worse, not better. Because now you have to write code for two
> possible platforms, both calling themselves Lua 5.3, but actually with
> different and incompatible functionality. What could possibly go wrong?

> Could we also please have a commitment to full documentation of
> incompatible changes, with explanation of what needs to be done to older
> code to make it work?

I agree with Simon here as the surprises with things breaking when the
new version is release are in my experience mostly caused by two
reasons:

(1) Lua is compiled with compatibility settings ON by default
(2) The documentation only lists deprecated, but not eliminated changes.

This means that when Lua 5.2 comes out, all the deprecated changes
still work (and they are documented in Lua 5.2). If you are slow to
update your code, by the time Lua 5.3 is out, things break and you
wouldn't see why from looking at Lua 5.3 documentation.

As discussed in the sister thread on documentation, I'd welcome two
changes to the documentation: (1) a subsection on removed features
(maybe with a link to the previous version where they were deprecated
to avoid duplication), and (2) a reference that a particular
deprecation/removal is controlled by a define. I realize that all this
information is in luaconf.h, but it would be very convenient to see it
in the documentation as well, especially given how short the
INCOMPATIBILITIES section usually is.

So, for Lua 5.2 I'd expect to see something like this:

* Function unpack was moved into the table library and therefore must
be called as table.unpack (controlled by LUA_COMPAT_UNPACK or
LUA_COMPAT_ALL).

for Lua 5.3, I'd expect to see something like this:

* Function unpack was moved into the table library and therefore must
be called as table.unpack (controlled by LUA_COMPAT_UNPACK or
LUA_COMPAT_5_1).

(having different defines is an argument for copying this information,
rather than linking to it).

In terms of practical approaches, I tend to make changes by sticking
to a subset of supported functions and adding compatibility functions
when appropriate; for example, I still use setfenv/getfenv, but they
are made to work for Lua 5.2 and Lua 5.3 (as much as possible). An
alternative would be to write code in a Lua-5.3-style and use
lua-compat-5.3 (or earlier lua-compat-5.2) to let it run on Lua 5.1
and Lua 5.2.

I think the Lua team took a sensible approach for deprecating/removing
functions (as they keep them available for one or even two versions),
but it may still seem like being not enough given that users can
compile Lua with different settings and still expect things to work.
To minimize the chance of this happening, I agree with Roberto's
suggestion to test things with Lua compiled without any compatibility,
as this will expose any issues with the code before the users see
them.

Paul.