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