EIP 005: Versioning System

[lukevp]

I think it’s a good idea to split host API and plug-in API compatibility like this and version them separately. the plug-in compatibility is gonna be the real bear, because releasing a new version of your extism-using product will break all existing plugins if it versions up the runtime to a plug-in breaking version, which is a shame. The host SDK and runtime compatibility are almost not an issue since it’s all on the developer side (but nice to think about them anyway :)) . If you’re not careful though you could easily get into the Python 2 to 3 situation on the PDK side.

One thing you could consider is how the plug-in API could be designed to have escape hatches so future runtimes could emulate compatibility and keep older versions working if they desired. eg. If I could have a blue-oyster that’s latest of all versions, but I could have a (probably bigger, slower) version like blue-oyster_barnacle that supported 2 pdk versions, I would definitely use that. That would let greenfield apps choose not to support legacy plugin coding models, but brownfield could keep running some backwards-compatible version.

An example from the Python 2 to 3 was converting print from a statement to a function (print “a” vs print(“a”). From a language design perspective they wanted to make this change. However, it wasn’t truly breaking - they could have supported both forms if they really wanted to, or allow the runtime to run in a “compatibility mode”. I do think this should be opt-in though, not required for all users.

You could also introduce a layer of indirection and develop the code as requested capabilities and supported capabilities instead (taking your example from 2 to n). Then each logical area of the code could be its own version - like when cancellable plugins were introduced. Then the PDK can just suggest to the runtime which capabilities it needs, instead of hardcoding the comparison to the color-creature combo.
That would have a benefit too that you could not even require upgrades of plugins that didn’t make use of capabilities that had breaking changes
I think your solution is probably sufficient or close though, just throwing some ideas out