Adapt Semantic Versioning?

[Tyron]

There has been a discussion on how version numbers on each new release should be increased. The whole description is on semver.org

But here is a summary:

• Change the major version if it has the potential to breaks mods
• Change the minor version if it adds new features
• Change the patch version if it adds only bugfixes

My current non-standard way of versioning:

• Major version change (1.0.0 => 2.0.0): New features if minor version would end up being double digit
• Minor version change (1.0.9 => 1.1.0): New features if the minor minor version would end up being double digit
• Minor minor version change (1.5.1 => 1.5.2): New features, not ending up being double digit
• Patch version change (1.5.1.1 => 1.5.1.2): Just stability/bug/fixes, new features discouraged

The new, more standardized, system of versioning, would mean:

• The new upcoming version 1.5.2 would become 2.0.0 instead
• The major version would increase fairly rapidly in the coming months, since the api is still under heavy development (I would assume we would end up with game version 20.x.x in 1-2 years)
• The version number becomes more aimed at modders so they can check for version compatibilty. This is good because modders can more easily see if they need to update their mods and the mod manager could also specifically test for these version numbers so see if a mod is potentially outdated
• Feels less pretty than the current versioning system? I dunno. I personally like the current versioning, so I'm undecided if i should go for (personally perceived) elegance, or clearly defined + usefulness for modders. Alternatively I could also keep the old system and have a single "api version" number that changes every time a release would break mods.

[heptagonrus]

I am an ordinary player, not a modder. Why ordinary players need version number?
Probably mostly to see very quickly after taking a break from the game, has the functionality changed significantly enough to return.
Without re-reading the whole News section.

Because if a player is playing actively and reading forum daily - they know what was updated, they don't care about the number much, just to see that they use the older one and to know to download the latest version.

So for me the comfortable versioning would be something like <big functionality update>.<small functionality update>.<bugfixes/tweaking>. Each number is a positive integer.
Probably many ordinary players would expect version to be: <big change>.<small change>.<bugfix>
So 0.*.* means game is early access. 1.*.* - all initial functionality is done. 2.*.* - kinda a DLC is added.

Neither of the systems you mentioned helps me with that  Actually I thought the current system was the my mentioned "comfortable" one.

Another user-friendly approach can be if the major version number change means world wipe required, or preferred. I.e. new ores generation, new biomes, etc.

All said refers to a single-player unmodded game. Ofc when the game relies heavily on mods, and most players will use them - it would be important for them to quickly know that the mods are incompatible.
So I guess from the "allowed" two I would prefer the "semantic" one (hate their name tbh, semantic exists in every versioning variant, they kinda announce that only their versioning has sense  ), since it allows all that the current has, also helping modders and mod users.

[Guest HelDM]

I personally don't really care what number is displayed, but I do want it to make sense for developers AND modders. So I didn't vote for any option.

Imho 'prettiness' is a non-issue. Functionality should be KING. If a pretty system makes it hard for modders (and in some sense developers) to make and update content, then by all means give me the ugly version ;-)

I don't think it matters what system you pick, as long as you consistently apply it so it makes sense for everyone (especially content creators/eg. modders other then yourself). I think part of your vision is to make this game easily moddable, consider that before anything else. listen to input of the current mod team. Once you pick something, stick with it. 

edit: reading back the orignal post, my opinion would align mostly with 'adapt semantic versioning... oops, so I voted for it

 

[tony Liberatto]

In my experience, the versioning system does not define the success or failure of a game. It does not also define how heavily moded or not that game will be. If people like the game, they will mod it, even if there is no actual support ( hence Minecraft).

That said, my OCD, asks for an easily comprehensible system. A system that makes easier for the player to see if he/she should update his game immediately or if he/she needs to wait for the mods to get updated. Also, will this break my existing world?

They may complain, but people capable of coding are too smart to use the argument that they cannot understand your game versioning. They cannot use stupidity as an excuse. 

Now us poor players, we are the ones who need clear big color letters:

"SAFE TO UPDATE": Just bug fixes.

"WILL BREAK MODS": Be careful, it may break your mods.

"WILL BREAK WORLD": Be prepared to start all over again.

No matter what system you use, you still should make very clear to all players when releasing an update, which case is it.

As far as the numbering system goes, if you think you can live with it and feel like conceding this minor victory to the modding community, them go for it and change it to make them happy.

 

[copygirl]

A lot of points (with me obviously rooting for 100% SemVer conformity) were already brought up in this thread:

 

1 hour ago, Tyron said:

Alternatively I could also keep the old system and have a single "api version" number that changes every time a release would break mods.

I like that. The game content / survival mod could certainly have its own version, split from the modding API / engine version.
Heck, you could even have a separate API version for the survival mod that modders would depend on. (Maybe important since I use it for CarryCapacity?)

14 minutes ago, HelDM said:

I personally don't really care what number is displayed, but I do want it to make sense for developers AND modders.

The thing is that Vintage Story has a public modding API and that's when versioning really becomes objectively important, whereas developers can version their game in any way they want that'll "make sense" to them. Minecraft had pretty crazy versioning in its early days. Streets of Rogue (an early access game) has versions such as "47f". Mindustry goes with "3.4 Release / Build 33". The point of SemVer is that each number increasing isn't subjective - they have defined meaning, something very important to modders.

3 minutes ago, tony Liberatto said:

A system that makes easier for the player to see if he/she should update his game immediately or if he/she needs to wait for the mods to get updated. Also, will this break my existing world?

Breaking worlds can be done through a separate mechanic and shouldn't be linked to the version. As you said, there should be a warning if this was the case. But even then, it shouldn't be all too difficult to update old worlds to a new format or so. Since the API version would be only important to modders, such a "world breakage" could be part of a bugfix release (2.10.2 -> 2.10.3), meaning that all existing mods would continue functioning in a new world.

[Stroam]

I don't like the idea of having multiple version numbers because keeping track of them and matching them up is a pain. If the system isn't simple people aren't going to use it. I like:

[Major game mechanics change].[Added content and mechanics].[bugfixes].[Modding API changes].[API additions]

• Major game mechanics would be like a change to the entire combat system, or the new mining system I listed on the forums, and other changes that drastically change the way the players does things in the world. This should rarely happen, but will happen. It should come with a title because titles are more exciting than number changes.
• Content and mechanics addition would be like bees, or adding leather processing. It's adds a new mechanic but doesn't fundamentally change old mechanic. Also includes minor changes such as changing the way firepits work. No title for these updates because they don't need to be exciting even if they are exciting additions. Just version 3.blah works just fine.
• Bug fixes I don't need to go over
• Modding API changes I don't need to go over
• modding API additions I don't need to go over

I support [double digits].[triple digits].[quadruple digits].[unlimited digits].[unlimited digits] 

triple digits to content because once you've added 1000 content changes, that adds up to a fundamental change to the game and should roll over. The quadruple digits for bug fixes is because as the code base grows for Vintage Story the amount of bug fixes between between stable release is going to go way up and you shouldn't feel pressured to change it to a content updated until you hit a significant number of bug fixes. At that point it is a content update to fix your rather buggy last version. Content updates should obviously reset bug fixes.

API additions should only get reset when API changes increase because additions don't break old mods but changes do. API changes should never get reset. If I have a mod that is really really really old and no API changes have happened since, it'll still work and the numbers should reflect that. I get not all API changes effect all mods but API changes don't say this mod will break, it tells people this mod could break. If anyone suggests keeping multiple numbers for different parts of the API I'd call that versioning hell and is not needed.

When displaying in game it should be [Major game mechanics change].[content added and mechanics].[modding API changes], with the full five numbers in an About button in the menu on the home screen and another about button on the in-game menu screen. Players don't need to know if they have the latest bug fixes in a stable release because there should be no bug fixes for a stable release. They also don't need to see API additions because API additions won't break any mods they already have downloaded. API changes they need to see though because if the mod they have breaks, that's going to be the first thing they should check.

All of that said I'm only thinking about survival. Other game modes should probably have their own versioning numbers. This is what makes sense to me as a player, and me as a modder. For those who may be more hard core SemVer fans, this should appease them because from what I understand this is kinda how SemVer does it if not the same order. For players the API stuff means very little until their mod breaks, then they want to know why and having one number "API changes" helps give them something to point at without having to learn how any of the versioning works.

[cynthia]

I voted yes but I would like to add a request, add an api version that is seperate from the content.

It does not need to be visible or anything but for modding it would be nice.

[tony Liberatto]

So many ideas an possibilities.

I do not like the idea of having different version numbers for different parts of the game.I think in the end it will just create confusion.

I can already see the conversations,

• -- So, what version are you using?
• --3.7.4
• -- But is it the Game Version or the API version, or is it the Old Creative Version?

One Game, One Version Number for the whole Game. So what if this Update only added features for the survival and nothing changed for creative? Explanations if you need to update or not can go on the News when the Update is released.

If something was important enough to be coded and released it should be important enough to change the Version Number.

What shape this version number will have is unimportant. As long as it has a method and is easily recognizable by everyone.

[copygirl]

59 minutes ago, tony Liberatto said:

But is it the Game Version or the API version, or is it the Old Creative Version?

I'm pretty sure the survival mod version is the one that would predominantly show up in the main menu.

1 hour ago, tony Liberatto said:

What shape this version number will have is unimportant. As long as it has a method and is easily recognizable by everyone.

Unimportant to you, maybe, but not modders. A proper versioning system will be incredibly important once we have a mod repository and dependencies become more prominent and hopefully stable. And, on the contrary: To end users, the version number doesn't need to be recognizable at all! It just needs to be something unique. It could be a single number that goes up for every release, or the date of the release.

 

I hope that, in the future, all we'll have is a single engine version along with a mod repository that doesn't just ship custom mods but also the Vanilla game content. You could get notified if a mod requires a game (engine / API) version that you have not got installed yet - or continue playing with the old one. You could have multiple versions of the same mod downloaded, using only the one present on a multiplayer server you connect to. And no, this will definitely not work if you use wishy washy versioning, where anything can break at any time. Hence why I'm really trying to show everyone why this is so important. It might be a bit weird in the beginning, but I'm sure that we can work out the kinks and eventually have a good standard for the modding community.

[tony Liberatto]

OK copygirl, I voted yes.

[copygirl]

By the way, I just want to add, that in my opinion, the API is currently still in a fluctuating state where changes will be made quite often for the sake of improvement. So, pretty much, right now we're at version 0.x.y if the team were to follow SemVer. So I either suggest to just stick to 1.x.y until the API is stable, and only then go to 2.x.y, or, even better, keep the current version as the survival mod version and start over with the API version (0.x.y).

[Tyron]

3 hours ago, copygirl said:

By the way, I just want to add, that in my opinion, the API is currently still in a fluctuating state where changes will be made quite often for the sake of improvement. So, pretty much, right now we're at version 0.x.y if the team were to follow SemVer. So I either suggest to just stick to 1.x.y until the API is stable, and only then go to 2.x.y, or, even better, keep the current version as the survival mod version and start over with the API version (0.x.y).

You mean stick to the old versioning scheme until the api is stable? Also I would really dislike backward version jumps, that's confusing in so many ways.

[copygirl]

2 minutes ago, Tyron said:

You mean stick to the old versioning scheme until the api is stable? Also I would really dislike backward version jumps, that's confusing in so many ways.

More like "Add a completely new version for the API", and you can already start using something like 0.x.y.

[tony Liberatto]

Please, pretty please. No 2 Version numbers for the same Game. It will just get confusing.

Get me a 10 digit number "123.456.678.90", Use Letters "A23B45C67", Use dates "1.2018.03.14.05". But use only one Version number for the whole game.

I have tried to use different version numbers for parts of internal documents in a big Network, in the end, people had no idea what went where.

So you made a change to the API, but that does not affect the common player and he does not need to update his game, no problem, you still should change the version for the whole game, the same thing the other way around if a change does not affect the API.

Give everybody the One and the same number. No matter what parts of the game got changed.

[copygirl]

On 3/14/2018 at 1:03 PM, tony Liberatto said:

No 2 Version numbers for the same Game. It will just get confusing.
[...]
Give everybody the One and the same number. No matter what parts of the game got changed.

By that logic, should mods also have the same version as the game? Should each released game version have its own mod release? Should there only ever be one release per game version? If your answer to any of these is no, I would like to point out that the survival game content technically is just a mod on top of the engine. We could benefit from game content being released independently of engine / API changes and the other way around.

[tony Liberatto]

It's hard, It's very hard for me to disagree with you. I really like so many of your ideas and am so grateful for so much that you do for this game. Before anything let me say Thank you. This game would not be as enjoyable as it is without your cooperation.

Now, as far as the Version number goes. 

For Mods, I would prefer if they all were at least prefixed with the game version that they were code over. Even if they keep working for many new versions, it would give an immediate information to the player about how old that code is and that if it is too old it could potentially have more issues. 

I understand enough to know that just because a recipe is added to the survival game it does not imply in any way changes to the game engine. But the game has changed and the player experience will be different.

The other way around is not always the same. Just because a change was made in the API, it does not imply any change for gameplay, and the player will keep doing everything the same way it has been doing.

Per your idea, we would have at least 3 version numbers for the Game. 

API  - Version.

Creative  - Version.

Survival -  Version.

Now I ask will we have individual packages for each version? Will the player have to assemble the game, putting those versions together?

I don't like it. 

I think having one and only one Game Version does not make the mod maker life harder in any way shape or form. It does not actually alter the Developer work. But having a whole bunch of version numbers for each small part of the game makes the life of the common player harder, and it creates more problems than it solves.

For me the argument is easy, was there a change in the game software that is packed and distributed to the player? No matter how small that change is if the answer is yes the version number must change.

I would not be against having a new version in Development mode until is ready to be distributed. So Modders would have an easy access to it. But once it is released to the public it should be just one number.

Like I said before, for the common player it does not matter much what versioning system we are using, as long as there is some logic to it and consistency in the way the numbers progress.

In the end, we all want the same here. To make this Game a huge success and have as many players as possible to buy it and enjoy playing the game.

I do not believe I have condescended with the common player when I say that multiple version numbers will be confusing. I really think it will create more issues and a lot of answering the same questions over and over to new players.

So far I can't see any benefits to multiple version numbers. Unless you think that the ability to release a package with just adding to the survival or creative mode with a specific version number for it is actually an advantage. 

The whole game can be as easily packaged and released with a new version number without much effort. It could just be released as an update for people that already have the game. Or even better have only the in-game update button to call for the update download and have it on the web page under a menu for updates.

The whole point for me is that all conversations between players, Developers, modders, server owners will always be around one version number. there will be no need to ask the player, for each part of the game version number that he is using.

So, give me a big number but do not give me separate packages with different numbers. Please understand that I am talking about the public version number and the version that gets officially distributed to players on the game website. To have a temporary API number for Development is completely acceptable, as long as is kept maybe in the Github, or somewhere else where common players have no access to it. Once the main developer decides is time to release an update it should package everything together and have a new version number.

 

I will quit now. If I haven't yet convinced you that my concern is to make the life of the common player easier and that in the end the player is the client and we should do everything in his benefit, continuing this rumble will not help and maybe will get me on your wrong side. Please, no. I admire your work too much for that.

Thanks, Peace and love.