Version Number Semantics - Replace 'major' with date-month?

[DanVanAtta]

Summarizing a decision point in: #4346

context and example

Current version number has 3 numbers, example:

1.10.13616

• major
• minor
• build number (assigned automatically on successful merges)

Note:

• 'major' and 'minor' are used for compatibility checks.
• Not quite a semver

Problem to solve

• The 1 in front is not very meaningful, not clear when it should be changed and what meaningful value it provides over the 'minor' number. It seems to be, just-another-number, clutter.

Acceptance Criteria/To resolve:

Should have a reasonable meaning and objective definition of when we would increment the major version, eg: 1 to 2. Alternatively we can choose to drop it or replace it.

My Suggestion

Relace the 1 with current year-month and use only 'minor' for compatibility checks. EG:

2019-01.10.13616

[ron-murhammer]

I'd probably vote against this as I don't think year-month really gains us much and just causes the version number to be longer and tougher to read.

[DanVanAtta]

Do you have an alternative suggestion @ron-murhammer ? This is not a yes/no vote but a problem to solve with desired outcome.

Dating to year/month is new data that we are not getting otherwise, it's somewhat useful to ballpark when a version was created. I'm thinking dev builds can replace the build number with 'SHA' to create a valuable triplet of info. Thinking about automatic user-uploaded bug-reports, the date can give us a ready reference to how old a version is.

It is a choice to drop the digit altogether.. Keeping this eternal 1 around is not particularly helpful. "no" is not an answer to the problem here.

[ron-murhammer]

I'm generally ok with the leading 1 and there is always the chance we would push to truly make a v2.x if say we did a massive UI overhaul and listed it on steam or something. Otherwise I'd be open to just dropping it if the majority of devs feel having just 1 version number + build is better. Its about a wash for me.

[DanVanAtta]

It's easy to get used to it.. Agree that is the likely case for a v2, thinking ahead, hard to imagine what or when we would see a v3 or v4. Eventually I'd like to see the project closer to a continuous release model with auto-updates being relatively transparent and pretty frequent.

We could agree instead on a medium/long-term release cadence. EG: beginning of every 3rd month we cut a 'latest' release. This idea is borrowing from Ubuntu versioning and gives the date additional meaning.

[RoiEXLab]

@DanVanAtta As long as we could imagine what would happen on a major version change the current version model seems sufficient IMO.
We could always change the versioning model when we reached the point where no major incrememtation actually makes sense.
However in order to do that we should probably no longer serialize a Version object in savegames/send them over the network, but instead store a raw string to be able to freely change the version model anytime without having to break compatibility.

[simon33-2]

It would be much easier to accept change in this area if we could get backward compatible save games. Otherwise it just seems all too difficult.

[DanVanAtta]

@RoiEXLab no disagreement current is sufficient, my suggestion is that it is actually excessive.

we could imagine what would happen on a major version change the current version model

I think we can suggest reasons to go to a v2 or v3, if we can find a definition of what the number means so we objectively know when to change it, that would be great. In the meantime I'm leaning to us dropping it, or changing it to represent something else.

However in order to do that we should probably no longer serialize a Version object in savegames/send them over the network, but instead store a raw string to be able to freely change the version model anytime without having to break compatibility.

I thought Version.java was behind a serialization proxy, in theory that proxy would have the same effect. Serializing the as a string would be a good move IMO, but it's a bit independent of if we change how we define version number.

@simon33-2

It would be much easier to accept change in this area if we could get backward compatible save games. Otherwise it just seems all too difficult.

Serialization proxy should help, beyond that, save game compatibility is already broken so no difference if we change version number this release.

[DanVanAtta]

An idea:

major.minor.patch.build

• major
  • maps from previous game cannot be loaded
  • save games from previous version cannot be played
• minor:
  • network connections to previous version do not work
• patch
  • important bug fix(es) available
  • significant new feature is available
• build:
  • travis build-id

We can use this flow chart to know which version to increment:

From a users point of view:

• build update: no need to update
• patch update: should update
• minor update: have to update, but can continue playing after update
• major update: have to update, any previous saves/maps may no longer be playable

Update Added definition from users POV

[tvleavitt]

Seems reasonable to me. If I'm hearing right, y'all are thinking about a major, backwards compatibility breaking upgrade at some point, relatively soon(?), so there'd be a rationale for the leading digit in this scheme. Regards, Thomas Leavitt

…

On Fri, Jan 11, 2019 at 9:34 PM Dan Van Atta ***@***.***> wrote: An idea: major.minor.patch.build - *major* - maps from previous game cannot be loaded - save games from previous version cannot be played - *minor*: - network connections to previous version do not work - *patch* - import bug fix(es) available - significant new feature is available - *build*: - travis build-id We can use this flow chart to know which version to increment: [image: version-flow] <https://user-images.githubusercontent.com/12397753/51069660-64d83e00-15e8-11e9-8961-4c9c3d393308.png> — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#4548 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AEPTgXWt3XLh2sf2s0MuUk7zlupOHqthks5vCXPMgaJpZM4Z4xmv> .

-- Thomas Leavitt Internet enabled since 1990

[DanVanAtta]

Thinking on this a bit more, there are some really solid benefits to: #4548 (comment)

For users

• they'll know if they need to finish up save-games before upgrading
• they'll know if they need to re-install before joining new-lobby
• they'll know if there are updates they should pick up

compatibility testing automation

We could at long last automate compatibility testing.

To explain how that would work:

• We build an integration test that reads major version number, and for example would download a 2.x-compat.zip file that contains a number of save games and map XMLs. The test loads each file from the zip and the test then succeeds if each file can successfully be loaded. In the case of an explicit version number update and for example no 3.x-compat.zip file can be found, then the test will no-op and succeed.

• Travis, after a successful merge and build will read latest major version and also check for a 2.x-compat.zip file. If the file is found Travis will no-op and continue. If the file is not found then Travis would generate it by launching an app that would record the save games and map XMLs and upload a new file, eg: 3.x-compat.zip

Checking network would be similar with two differences:

• compat file would specify minor version, eg: 2.1-server.jar
• if current version is not found then a server would be launched from latest source insteasd of from jar file.

To get that up and running we'd need to install the travis piece first to start generating the baseline content. Once that is in place we'd add a test that downloads the files and loads them.

[RoiEXLab]

@DanVanAtta
2 Things:
In my opinion your proposal could achieved by keeping the current system. A new build isn't something super special in most cases anyways.
If you're still convinced having effectively 4 numbers is key, I'd like to go with semver syntax, which allows build numbers in a well defined way to exist.
See https://semver.org/#spec-item-10

[DanVanAtta]

@RoiEXLab the current system is without meaning/definitions. Should we be on 2.x? What does a 1.11 vs a 2.0 mean?

I'd like to go with semver syntax, which allows build numbers in a well defined way to exist.

Please note:

Without compliance to some sort of formal specification, version numbers are essentially useless for dependency management.

We do not use version number for dependency management. Hence why it does not quite make sense and misses the audience. The audience does not really care if an API is compatible or not if they can still play the game: https://semver.org/#if-even-the-tiniest-backwards-incompatible-changes-to-the-public-api-require-a-major-version-bump-wont-i-end-up-at-version-4200-very-rapidly

If we followed that proposal, could we automatically check compatibility as part of PR builds? What would it look like?

A link is not super-helpful sorry, please define examples of when and what would change numbers specifically in this project. We need to be concrete about it please.

[RoiEXLab]

@DanVanAtta

We do not use version number for dependency management. Hence why it does not quite make sense and misses the audience. The audience does not really care if an API is compatible or not if they can still play the game

Sorry if I wasn't clear enough: I was only suggesting to go with the syntax exclusively. Without any semver meaning of any kind, so we could in theory use a standard parser instead of writing our own for example.

[RoiEXLab]

So instead of 1.2.3.12345 we'd have 1.2.3+12345 instead to separate the build number (which doesn't really convey any meaning at all) from the rest.
Just a visual difference.

[DanVanAtta]

Ah, thank you for the clarification. The + makes sense 👍

[simon33-2]

The problem with definition of XML syntax updates = major version bump is that it is already violated by version 1.9.

We only tried once or twice to put out 1.9.0.1 or greater so I'm not sure that the idea of 1.2.3+12345 would see actual use?

I don't really feel that major.minor.build is sufficiently broken to be worried about it.

[DanVanAtta]

If the version bump is already violated, are things not pretty broken?

If no update, what does our major version mean?

You don't have to view major version bump as XML syntax updates as it can go for save games, which could involve delegates. Another way to define it from a users perspective:

• build update: no need to update
• patch update: should update
• minor update: have to update, but can continue playing after update
• major update: have to update, any previous saves/maps may no longer be playable

[DanVanAtta]

Latest suggestion on table is these definitions: #4548 (comment) with this format: major.minor.patch+build

• Are there any other definitions or alternatives that we should consider?
• If we would like to stick with current spec, are we able to clearly and reasonably objectively define when each version number would change?
• If we're are starting to settle on the suggestion, can we foresee any potential problems with the latest definition?

[DanVanAtta]

@simon33-2 even if you have doubts on utility, does the proposed update make sense to you?

@ssoloff @ron-murhammer kindly weigh in, any thoughts on this idea for version number definition:

• Version Number Semantics - Replace 'major' with date-month? #4548 (comment)
• Version Number Semantics - Replace 'major' with date-month? #4548 (comment)

[simon33-2]

@DanVanAtta If we went with 1.2.3+12345, I'm still unclear on when we would move on the "3" number. If it's open to interpretation then how will it not repeat 1.9.0.0 when the last digit was never actually moved on? Which begs the question, what's the point of any change?

[DanVanAtta]

'3' is the patch update to indicate notable and compatible game revisions. TBD if we agree on the big picture before we give that a more specific definition.

1.9.0.0 had a number of problems, in part previously the version numbers were moving at the final digit and it was by agreement we would start increment the '9' and use the '.0' and chop off the last '.0'. Because we were going to remove the last '0' value, why change it?

what's the point of any change?

• clarity to uses what the version numbers mean
• useful indicator to users when they need vs should update.
• clear definition, helpful to dev
• definition is well enough defined for major+minor that we can verify automatically when there is compatibility. In theory if we are being diligent as TripleA developer, just about any kind of change should be verified against lobby client/servers of different versions. We won't need to do any of that anymore.

[DanVanAtta]

@simon33-2 I don't think I answered your question directly regrettably.

I still think having 3 numbers is a more meaningful way to go. For example, we are now encouraging users to upgrade to a newer version of 1.9, the third number of your example would indicate that.

For example:

1.2.3+12345

vs:

1.2.4+12346

In the second, the third number means there are new features, something new to pick up for a user that is still compatible with version 1.2. Perhaps it's worth noting that some code changes that change the build number are not user facing at all, like refactoring to clean up or that is in prep of other changes. I think in practice we'd change the 3rd number when we think it's worthwhile for a user to upgrade to a new version.

[DanVanAtta]

Topic is resurrected in: #4875