Strategy for versioning a Go implementation of Lua (Mapping 5.4/5.5 to v1/v2?)

[Arnaud Delobelle]

Hi everyone,

I maintain golua (https://github.com/arnodel/golua), a Lua
implementation written in Go.

The project currently implements Lua 5.4 (tagged as v0.1.x). I have
recently completed a branch implementing Lua 5.5. Since Lua 5.5
introduces changes that are incompatible with 5.4, I need to manage
this breaking change carefully before releasing a stable v1.

I am trying to reconcile Go's Semantic Import Versioning with the
external Lua language specification versions. I have two dimensions of
versioning here: the Go API version and the Lua Language version, but
I don't want to overcomplicate things (one important factor is that I
do this in my spare time!),

My current intended approach:
I plan to release the current Lua 5.4 implementation as v1.0.0 and the
new Lua 5.5 implementation as v2.0.0 (using the standard /v2 module
path).
- Pro: It follows standard Go idioms for breaking changes.
- Pro: It fits my maintenance workflow. I plan to develop on the
latest version and backport fixes to the older Lua version. Keeping
the versions on separate branches allows me to git cherry-pick changes
easily.
- Con: The version numbers will be permanently desynchronized from the
Lua spec (Golua v2 implements Lua 5.5; a hypothetical Golua v3 would
implement Lua 5.6).
- Con: It implies v2 is a strict upgrade, whereas some users might
need to stay on v1 purely because their scripts rely on the Lua 5.4
spec.

Alternative considered (but likely rejected):
I considered restructuring the repository to expose versioned packages
(e.g., github.com/arnodel/golua/lua54 and .../lua55). However, I am
leaning strongly against this for two reasons:
1. It would require a massive refactor of the existing codebase.
2. It breaks the backporting workflow. Since the code for the two
engines would live in different directories, I could not easily
cherry-pick bug fixes from the new engine to the old one.

I would welcome any insights into this situation, in particular:
1. Is the version number mismatch (Go v2 vs Lua 5.5) considered
acceptable practice when wrapping/implementing versioned external
specs?
2. Does the standard v1 (5.4) / v2 (5.5) split sound like the most
robust way to handle this, assuming I want to maintain the
branch-based backporting workflow?

Thanks for any advice!

--
Arnaud

[ben...@gmail.com]

Hi Arnaud!

I think your suggested approach of Lua 5.4 -> v1 and Lua 5.5 -> v2 is pragmatic and reasonable.

One other alternative is to keep everything in one branch and support both, making the Lua version a runtime-configurable thing. For example:

rt := runtime.New55(os.Stdout) // type *Runtime with an internal flag set, or type a new *Runtime55

// or

rt := runtime.New(os.Stdout, runtime.WithLua55()) // type *Runtime

This would only be good if there was a ton of commonality between 5.4 and 5.5, and you'd need just a few runtime checks in a few places to differentiate. Otherwise the codebase could become messy if there are many large differences.

-Ben

[Stephen Illingworth]

My advice would be to not move to v2 for Lua 5.5.

If it were me, I would reserve changing the major version only for when the Go functions that control the runtime are changed.

To my mind, the purpose of the v2 idiom is to help future compilation and maintenance of a Go project. From what I can tell, adding support for Lua 5.5 on it's own wouldn't affect compilation of the Go project. It would affect what Lua programs can be run, but that's a different issue.

I've seen another Go project that tried to update the major version when breaking changes were introduced in the external dependency. My opinion was that it got very messy, very quickly and for no benefit.