On the topic of versioning

[copygirl]

This is inspired by the recent 1.5.1 => 1.5.1.1 release which, due to renaming a method in the API, breaks any mod which adds their own block behaviors. If you have any idea about how versioning is supposed to work you might already see the issue, but if you don't, here's a quick summary:

Quote

SemVer is a standard that arose from the hell that is dependency versioning. People would just version things as the feel like it, and when you'd depend on other projects, nobody would really know what change in versioning will cause things to break and which ones won't. So smart people came up with a standard as such:

You have a version MAJOR.MINOR.PATCH.

• MAJOR: API breaking changes. Probably not compatible.
• MINOR: API additions and marking things as possibly breaking in the future.
• PATCH: Other additions, content, bugfixes that don't affect the API.

So, when simply comparing versions, 1.4.10 < 1.5.0 < 1.11.111 < 2.0.

Additionally, if you depend on the game's API (or another mod) of version 1.5.2, it would obviously refuse to load with 1.4.10 and 1.5.1, but it's also incompatible if you were to try to load it with version 2.0.

Tyron already noted that he'll avoid breaking API changes from patch releases.

But, back to the meat. Here's the changes I'm proposing, then I'll try to respond to critique, then I'll note the advantages.

• Use SemVer religiously. Set a good example.
• Split survival mod version from engine / API version.
• Build in proper version dependency, for example:

"dependencies": {
  "game": "1.5.2",
  "survival": "2.15",
  "carrycapacity": "4.2"
}

• Refuse to load incompatible versions according to SemVar rules.
• Anything in base survival mod or user created mods that respects SemVar should be in an API namespace.

In Discord I already got some response on this:

• "I prefer something different." (For example a more loosely defined REWRITE.MAJOR.MINOR.PATCH versioning.)
  Well, I used to prefer that as well. I generally tried to choose what felt right. And it's perfectly fine for a hobby project where versioning doesn't really matter. This is addressing any part of the project as well as mods where it would matter - more on how, later.
• "But, Minecraft did it this way. People can talk about what their favorite update was."
  Minecraft has no official modding API, and is giving their big content updates names now, too. Just because Minecraft did it doesn't mean it's good. Players won't lose anything by talking about the "Mechanical Power Update" instead of "Version 1.15". In fact, I will claim they will gain things.
• "It's confusing."
  That's outweighted by the benefits. If you think it's too confusing - such as players mixing up version numbers, you could show less information openly about the internal version and instead automatically include them in crash logs and other ways people can extract basic information about their current world. If you want to keep it, you could show both the engine / API version and survival mod version in the main menu.
• "This is too soon!"
  I agree. I propose starting to respect this versioning system with 2.x of the API, when major changes are less likely to occur too often.

Finally, here are some advantages:

• It makes things more consistent, possibly even more so if an eventual mod repository comes along, with which even the official survival mod could be served, as well as other community mods.
• It's very clear to the engine and to modders which versions will be compatible and which ones won't. If a user downloads a mod which depends on version 2.5 of the API, it will, ideally, continue to work for every 2.x release of the API / engine without breaking. A mod might continue working after a major version change, but if you're using a bunch of them, the likely answer is that it won't, and then both users and developers have to deal with the ensuing mess. Specifying a dependency with version is very explicit and shows intention, instead of vagueness.
• This doesn't mean this breaks every single mod when a new major version is out. Say 1.8.0 releases and you write a mod for it. Eventually, 1.8.4 comes out, in which it deprecates some old methods it wants to replace eventually. If a modder were to compile the mod at this point, they'd receive a warning message telling them about the change. The changelog would probably also include some information. One of the things it might say is "Major API changes frozen, it's safe to support 2.0.0 now." and then you can mark your mod as supporting version 1.8.4 and version 2.0.0 (which isn't out yet). There might still be a 1.8.5 and 1.9.0 release, but those will continue working just as well.
• On the other hand, if you write a mod and you're using old, unlikely to be changed APIs, or simply don't care, you could specify "*" as the version to depend on: Any version. With this you could explicitly state that you don't care or are confident enough that they'll continue working.
• Again, this should happen at a point where major API changes will happen relatively rarely, perhaps every quarter or half year. It might cause people to have to maintain their mods a little bit more often, simply pushing out a new version, thereby explicitly confirming that their mod still is safe to use with the major version.
• Additional headaches could be avoided by splitting mods up in to smaller bits, each for a separate function.
• Alternatively to splitting up mods, they could provide modules which each would have their own version associated with them, on which mods could depend, instead of the entire mod. So for example you could depend on "game:metalworking": "2.4.0", and an update of "game:foresting" from "3.7.0" to "4.0.0" wouldn't affect you.
• Another side effect of this is that mods could provide certain modules though an API, that might in the future also be provided by a different mod. For example my mod might depend on an ore registry API to have its ores spawn in the world. But there might be two different mods which implement this API and do things slightly differently somehow. Perhaps there's a third mod which, instead of spawning ores in world, is meant to work in a SkyBlock type world and produces the registered ores when sifting gravel. Of course such functionality could be provided at a different level instead of a fully fletched .NET API, but it's something I thought was worth noting.

It might be a bit soon to mention this, but in light of recent events (*cough*), I thought it was important to mention, for brighter future!

[Milo Christiansen]

2 hours ago, copygirl said:

Use SemVer religiously

[rant]That is one problem I have with semver, Its proponents seem to thing everyone must use it or they are doing something wrong.[/rant]

2 hours ago, copygirl said:

Split survival mod version from engine / API version.

2 hours ago, copygirl said:

they could provide modules which each would have their own version associated with them

Welcome to version hell, where each release is tagged with a dozen different versions for each little bit. The API/CoreMod version split wouldn't be too huge, but why? It doesn't tell you anything a note in the changelog won't.

2 hours ago, copygirl said:

"It's confusing."
That's outweighted by the benefits. If you think it's too confusing - such as players mixing up version numbers ...

2 hours ago, copygirl said:

"But, Minecraft did it this way. People can talk about what their favorite update was."
Minecraft has no official modding API, and is giving their big content updates names now, too. Just because Minecraft did it doesn't mean it's good. Players won't lose anything by talking about the "Mechanical Power Update" instead of "Version 1.15". In fact, I will claim they will gain things.

How many MC version names do you remember and use? Do any mods mention that they use versions by name? No, and the reason why is because users need a short, clear, and easy to remember, way to refer to a specific version. Saying "the X update" will never replace version numbers since it is harder to connect a name to a version of the game. Version numbers are easier, because they are mostly sequential, 1.9 comes after 1.8. Is the X update newer than the Y update? No way to tell with names.

This leads to an important point: While a game is in active EA development, version numbers are for users. Since there are many more users than modders, a version number system that is easy for users is far more important than one that is easy for modders.

Any version split adds more things to remember and worry about. Users won't care what the API version is, they only care about the user-friendly game version, and if you make the game version less user friendly you make it harder on the user. You can't say "my mod uses API version X.Y.Z", because users won't know or care what the API version is. You still need to tie your mod to game versions.

"But I can just look at the API version and I'll know if something broke if semver is used!"

Whoa, not so fast! What broke? Well, you need to look at the changelog to find out don't you? So why not just put a little note at the top of the changelog: "This version breaks API feature X". Same basic effect, no need to confuse the users with complicated version numbers that don't seem to align with anything.

In short, I think the game should use simple "contentupdate.bugfix" version numbers more or less exactly like it does now, and let modders read the changelog just like they should anyway.

 

Finally, let's address the issue of refusing to load mods made for older API versions. Factorio does this. If your mod doesn't say it was made for 0.16, it won't load in 0.16. This is a pain in the rear. Every major version, all mods need to be updated, whether there were changes that effected it or not. Instead of the mod author simply running a few test and announcing it will work with the new version, they have to upload a new copy of the mod. No big deal right? Wrong. It raises the amount of effort required to maintain mods, and with lots of mods quickly becomes truly painful. For Factorio it isn't too bad, the major modders generally need to deal with breakage anyway, but all kinds of small mods are abandoned all the time simply because someone couldn't be bothered to change a single JSON file. As for a special "any version" syntax: What will stop everyone from using it? In that case you are right back where you started, just with an useless feature adding a touch of extra complexity to everything.

[capitalthree]

I'll throw in my 2 cents, because hopes for future moddability are overwhelmingly the primary reason I bought VS.

First and foremost, I think the most important part of copygirl's point, that as far as I can tell you didn't refute and hopefully agree with, is that there should be a clear understanding in the versioning scheme that versions below some level won't break compatibility.  To me, this is far more important than SemVer specifically.

As for SemVer itself, personally I'm partial to it.  It seems sensible, and as copy laid out, it helps everyone when people use a uniform standard.  I didn't see you propose anything resembling a uniform standard as an alternative to SemVer, is there one?  When your first point is that it's frustrating that proponents of something often say you're wrong for not agreeing with them, it's highly suspicious.  Your biggest problem with a different viewpoint should be an actual problem with their viewpoint, not the fact that they also disagree with you.

Now, copy cited some potential dissent to try to counter, which you seem to have misinterpreted as an admission that a SemVer scheme *will* be confusing.  There was no such admission and I don't see why it would be.  I would like to hope Vintage Story doesn't go through multiple digit numbers of completely API breaking updates, given the actual focus on moddability, so we can probably expect to see a single digit primary version and a double digit secondary version, leaving us with very similar version numbers to the short form ones people use to talk about minecraft.  If I understand correctly, there would be no reason to ever not be on the latest patch version of a given minor version, so given that the game has the basic ability to keep itself up to date, patch version can easily be hidden from end users.  You rant at length about how great remembering minecraft version numbers is.  You completely fail to justify a case for why the situation would be any worse here.  Minecraft version numbers actually look, you guessed it, a lot like SemVer!  (even though they're not, because the numbers don't communicate the same information)

On the topic of separating engine version from content version, it's overwhelmingly clear to me that this is the correct thing to do.  Yes, it would be possible for the dev to version them in lockstep just to have one version number instead of two, but here's the thing: a major promise of this game, and I should reiterate, the reason I excitedly forked out cash for it, was the promise that the base game is just another mod and not specially privileged over third party content.  If the developer has to release engine version bumps in order to put out content updates, you have to admit it's not a good look.  This isn't something that's going to objectively compromise it as a great modding base, but doing the version split really sends the message that you're buying a game engine *and* a game to play on that engine, and they are separate entities.  Does this confuse users?  Trivially easy solution... don't show them the engine version on the title screen.  Or do, in a smaller font.  The content is what they see and care about.  People setting up modpacks will need to know where to look for that information.

Do users outnumber modders?  Yes, overwhemingly.  Does that mean we should cater the *versioning scheme* to users?  You forgot to multiply by how much they care.  Do modders care about what the numbers communicate in a versioning scheme?  Absolutely.  Do end users care?  Well, by the numbers, the modern modded minecraft player clicks on pre-curated modpacks in a launcher.

Shorter responses to some other points:

- You claim splitting mods up so that parts that rely on more stable parts of the api won't have to be updated as much, will result in version hell.  Uhhh what?  The whole point is that many of those modules would be able to be much more stable targets, and this claim is made as a sarcastic assertion, but with no evidence that you're not just making it up.  That said, version hell becomes version heaven the instant you have a decent package management scheme, so we should just put that on the table instead of hiding from the entire concept of handling dependencies sanely.  The minecraft mod community with dependency mods seen as a bad thing, and people shading the same duplicate libraries into different mods just to avoid them, is not a model to be proudly following.

- Regarding simple contentversion.fix: contentversion is likely to become a 3 digit number, which seems ugly to me.  Not the end of the world, but you don't bring up any benefits to this scheme, either.  It could be workable for the game content's versioning, though it would be utterly nonsensical to use this instead of something like SemVer for the api versioning.

- Refusing to load mods: copy proposed a wildcard for versioning, so essentially modders would have the choice between locking their version compatibility or wildcarding it.  As far as I can tell, you just complained about both halves of that choice.  I am left with no response besides to rub the two halves of your paragraph together.

 

TL;DR: SemVer is fine, it's not magical but it's a standard.  If there is a better versioning scheme proposed, or a *sensible* reason not to use SemVer, I haven't seen it.  No evidence has been presented that SemVer will result in version numbers that are unwieldy or confusing to users.  The Vintage Story game content and the engine/API versioning should be separate because the logical separation of those two products is an enormous part of the value of both, to both consumers and modders, and regardless of the decision about what to show to users on the title screen, that separation should be clear to people who care.

[Milo Christiansen]

47 minutes ago, capitalthree said:

Refusing to load mods: copy proposed a wildcard for versioning, so essentially modders would have the choice between locking their version compatibility or wildcarding it.  As far as I can tell, you just complained about both halves of that choice.

Err, no. All I had to say about the topic is that any kind of version lockout ends up being bad, and a half baked way to circumvent it will simply make it even more redundant and useless.

Luckily Tyron has said there will be no such thing, at most there may be a warning message.

49 minutes ago, capitalthree said:

You claim splitting mods up so that parts that rely on more stable parts of the api won't have to be updated as much, will result in version hell.

Release something or other:
API part X v5.3.4, API part Y v2.1.2, API part Z v3.4.1, ...

What version does your mod need? Uhh... It's complicated.

53 minutes ago, capitalthree said:

When your first point is that it's frustrating that proponents of something often say you're wrong for not agreeing with them, it's highly suspicious. 

It means that you see the main thrust of the other's argument as blindly running twords a "standard", simply because it is the "right" thing to do. The problem is, standards are not universally applicable, and semver is not necessarily a good choice for a user visible version number in an evolving game.

[cynthia]

I will throw in my thoughts too.

There should not be any hard version lock down, so just a warning message but no refusing to work.

There should be a separate version for the game content and the Engine/API since modding is a big part of the game since the game itself is a mod.

Regarding splitting version between the game and the engine, well you can not really compare it to Minecraft directly since Minecraft is one "blob" with the game engine and game in one, but if you really want to compare it, in modded minecraft pretty much everyone uses forge which has it's own version, so yes there are 2 big versions in modded Minecraft too.

There should not be any breaking changes at the 4th level. 3rd level maybe if it is just a tiny thing that might break something but probably wont, 2nd larger changes but still not huge changes. 1st level huge changes like changing the world gen completely.

(A bit unrelated but copy mentioned it) I am totally for having a mod repository but there should still be easy to just add a zip/folder/c# file directly to the game.

[copygirl]

13 hours ago, Milo Christiansen said:

How many MC version names do you remember and use? Do any mods mention that they use versions by name?

I think you're forgetting the reason the versions are remembered in the first place. It's mods and modpacks. I remember 1.4.7 because it's the last version that had RedPower 2 (I think), 1.7.10 because it had lots of big, unique modpacks. And guess what? None of them worked in 1.8 anymore.

13 hours ago, Milo Christiansen said:

This leads to an important point: While a game is in active EA development, version numbers are for users.

Most early access games don't come with modding support out of the box, so I think this is a weak argument. And no, I very much disagree with your opinion that version numbers are for users. Many developers choose to show it to their users now, and it becomes a semi-significant informational bit for them, and therefore they choose how significant the content updates are to determine the versioning. Usually this happens without an API present or having it in mind.

3 hours ago, Milo Christiansen said:

API part X v5.3.4, API part Y v2.1.2, API part Z v3.4.1, ...

What version does your mod need? Uhh... It's complicated.

It's the other way around. You specify exactly what you need. The engine makes sure the depencies and versions are met. This should happen behind the scenes. It's not important to users. In fact, the opposite would be true if you had a more losely (and imo pretty useless) versioning system defined. Does ModX work with the newest version of the game? Who knows? The modules suggestion was in response to your criticism that you don't want mods to refuse loading when the MAJOR version changes when something unrelated changed that it doesn't really care about. Which could also be solved by only making major changes to the API pretty rarely and announcing breaking changes and marking things as deprecated well in advance.

13 hours ago, Milo Christiansen said:

As for a special "any version" syntax: What will stop everyone from using it? In that case you are right back where you started, just with an useless feature adding a touch of extra complexity to everything.

The point being that you explicitly state that you don't care. Otherwise mod developers are all forced to "not care", when they'd likely enjoy having some sort of assurance with the whole versioning thing. The version just becomes a meaningless, random set of numbers.

Just because the main API is using SemVer and enforces these rules doesn't mean the mods have to pay large attention to it. Big updates / increasing the MAJOR version number require a new release, and they likely would, anyway. The, in my opinion, huge upside comes from being able to write a mod for version 3.0 and getting an implied guarantee that this mod will likely continue working for any 3.x release of the API. So you can sit back and actually do less work than you would have to, because otherwise you need to keep track of every update, read changelogs and, ideally, test every feature of the mod to ensure it works. And then you have the same situation as in Minecraft: Mods taking a long time to update, possibly never doing so, because each update is a breaking change.

3 hours ago, Milo Christiansen said:

It means that you see the main thrust of the other's argument as blindly running twords a "standard", simply because it is the "right" thing to do. The problem is, standards are not universally applicable, and semver is not necessarily a good choice for a user visible version number in an evolving game.

In my opinion you're still lacking any convincing argument against SemVer. You're implying that I'm just claiming SemVer is better and the right thing to do for the heck of it, but that's not true. I have a number of points to back this up. Your opinion that versioning numbers need to be visible to users, you also have failed to sufficiently explain, the only examples being Factorio (version 0.x - which is in line with SemVer) and games without an API. And this need to have the version be visible and make sense to users seems to be the basis and reason for your opposition.

[Tyron]

Thanks for the lengthy inputs everyone, I very much appreciate the discourse. Just to be clear:

• I very much care about modders, as I was a mc modder myself for 4 years, and it sucks to be shrugged of or straight out frowned upon by the devs / mod api coders. 
• I always believe everyone should be given the opportunity to take responsibility for his own actions, and that without hurdles. If someone wants to risk crashing his game, he should be able to. This is why I do not want a hard version lockout for mods. We can present a sterner warning to users if they try to use outdated mods marked for specific versions, but in my opinion this should not be a hidden setting or straight out locked by the engine/modder.
   

@Milo Christiansen
Intuitively, I do feel inclined to keep the current versioning system. A version number that can be more easily associated with content updates helps marketing wise. You can more easily converse about updates with friends and with media outlets. But then again, I could try to limit breaking API changes to content updates, and we'd have the best of both worlds, I suppose?
What would change is that major version numbers are likely to increase faster than with the old system, but I suppose thats acceptable.

When thinking about it now, what I do like about semver is that it concicelsy defines mod breakage that a few lines of code can interpret as well. You only need to read a few numbers and you know if a mod is broken or not. That would help the engines mod manager to mark mods as possibly outdated.
 

[capitalthree]

Milo seems to have decided to reject my points, but by simply ignoring and not addressing all the arguments I made to support them.  I'm not sure how to respond to that without just repeating myself.  Yes, dependency management can be complicated... but Milo proposes no workable alternative, and ignores my explanation for why the situation in minecraft modding (where developers bend over backwards to avoid linking dependency mods) is a disaster.  Yes, if the thrust of copygirl's argument was *just* that a standard should be followed because it's a standard, that would be a bad argument, but uhh, that's just lazy reading.  Copy explained why it's a *good* standard and that was the point, please just go re-read.

Anyways, about a version lockout: my fear about not allowing a version lockout is that, no matter how strongly worded the warning is, there is a chance of the modder community establishing a culture of encouraging users to ignore the warning, and it will become both useless and annoying.

Tyron, if you limit API breaking changes to content updates, that is not the "best of both worlds."  Pegging the game engine release schedule to the game content will annoy the modders who wanted the latest API features but have to wait for you to finish a content update.  I'm going to double down: you NEED to decouple mod API version from game content version if you want the full respect of people like me who are looking primarily for a modding platform.  I already told you you can simply not show engine version to users, as they won't care.  Can you explain why this isn't acceptable?  I'm not in charge of you, and you already got my money, but let me reiterate: the promise of a *proper* decoupling between game and engine is *the* main selling point of this game to prospective modders, and why I made the purchase.  Splitting the versions will symbolize that decoupling very clearly, and will function as word-of-mouth marketing when minecraft modders are giving other minecraft modders the elevator pitch for why they should become vintage story modders.  Trying to softpedal that division will just make it harder to explain the appeal of VS to modders, and worse, if you actually start making engine releases wait for content releases just to keep up with lockstep versioning, that would be really really bad, and would send the message to API consumers who aren't using the base game, that they're not the priority.

[capitalthree]

I forgot to reiterate this, and maybe it's ok to put in its own post so people actually notice it this time:
WE NEED A PACKAGE MANAGEMENT SOLUTION!!!

Everything is going to suck without a package management solution.  All this talk about avoiding dependencies, or illogically lockstep versioning things that don't fit, is like proposing that we eat soup frozen because liquids are complicated.  Don't ruin the soup, just get a freaking spoon.  Package management is the spoon.  No end user should ever have to pick or see an engine/API version.  They should simply be choosing content packs from a menu that gets automatically filtered down by compatibility, based on what content mods can run with each other and what engine versions are supported.  This is the solution that will actually not suck.

Tyron, as the game's dev, you're in a position where if you create a sensible mod repository, all the modders will flock there and upload to it.  Then building a robust package management system into the game, where users simply pick content they want and you solve the constraint problem of dealing with engine versions for them, will be more work, but you'll have the most user friendly experience around for choosing and playing modded game content, and all without compromising on letting the developers follow best practices (ie, letting them break stuff into dependencies as needed, tag submodule version requirements differently as copy suggested, and give dependency mods their own versioning)

Every single argument here against copy's proposed versioning changes seems to boil down to "well it makes things slightly more complicated, if we continue to do absolutely nothing useful about mod distribution."  But let me tell you, you can dumb down the versioning scheme, lockstep the versioning schemes of two distinct codebases, and otherwise annoy modders, and it's still going to suck just as much for users!  If users have to get all their mods by downloading them individually and then retroactively letting a mod manager guess whether there are compat conflicts, it SUCKS.  I already have a full package management system with dependency resolution for minecraft mods, that I use to assemble my modpacks, and it's fantastic, despite being made out of scripts that scrape curseforge.  But of course, a third party package management system doesn't sent the message to devs that it's ok to sanely use dependency mods when needed now.

 

Conclusion: if you don't address mod distribution with dependency resolution, then you can make the best mod API in the world and the end user experience for assembling content into a playable game will still be just as shitty as it is with most other moddable games.  If you *do* address mod distribution with dependency resolution, then all of the arguments against moving to a better/split versioning scheme fall apart.

[Milo Christiansen]

I'll just say is disagree with large parts of the above two posts and not bother to break it down point by point. Trying to refute each point (often for the second time) would just be annoying and ultimately pointless. It is up to Tyron, and he seems to have a good handle on things.

 

Still, a few points:

A game designed for modders at the cost of users will quickly fail. VS should try to maintain a balance, not try to please modders at user expense.

Some kind of official mod portal built into the game is a good idea, but it is far too early to worry about it yet. Anything made now will only solve a not yet fully understood problem poorly. It is far better to wait until it is closer to the point where such a thing will be needed, and the requirements are clearer. Such a portal should certainly include the ability to automatically download dependencies. I do not, however, agree that this removes the argument against complicating the versioning.

[skol]

My 2 cents:

1. For the end user, the "game content" version is relevant. This one could be used to name the packages and announce the updates.
2. Having this in mind there should be no drawback in offering an API version as part for the mod management features as long as the mod can decide how strict the compatibility check is and what shall happen when the check fails (warn and run the mod or warn and unload the mod).