Magic Files for Map Indexing (map.yml file / description.html / preview.png))

djabwana

I was saying to make it be a string so that map makers can use any versioning system they want, and it would be used by the engine, including but not limited to sem ver. Right now, even assuming the version inside the XML goes away, there are often two different versions: the numeric simple count from triplea_maps.yaml and the "real" version - perhaps a tag, perhaps a thought in the map maker's head (this is after I rebalanced, but before I added cruisers). I'm suggesting that now is the time to open up the version to be an arbitrary string so that it can capture the "real" version, whatever it is. Map makers could literally set it to rebalanced-with-cruiser if they wanted - it wouldn't have to be numeric.

What complexities does that create? The only one is: when a map is out of date and needs to be updated. I'm proposing inequality. So if someone changes their new map.yml to now have rebalanced-with-cruiser-mod-2-with-dans-suggestions, we might suggest they use a new versioning system but the engine just says- this version is now different from the cached one on your system, would you like to update

LaFayette

It is an interesting point that inequality is enough and that the version values do not need to be a POSET (partially ordered set).

I don't think any problems that arise from this are necessarily deal breakers, but in sum they are general consistency problems and it is a goal to keep the learning barrier as minimally low as possible.

The problems I would be concerned with are:

Complexities for new map makers to learn. It's not as simple as "look at another map.yml, see how it is a number, increment that when you want to notify players to download". Instead it becomes nuanced and a person then has to make additional decisions rather than "this is how you do it". It is simpler when there is one way to do something compared to multiple ways.
A version change may not necessitate players to download an update. Perhaps you want your real version value to be 1.0.1, but you actually don't need to bother players with a prompt to update because there are no significant changes. The purpose here drifts, you would not want to update the map.yaml version value unless you want users to update their map, it would not be for tracking the actual version of the map.
Complexity of map update vs game update. That there can be many games to one map. There is an aspect to explain that some map makers like to version their game files (some maps have multiple XML files). This gets complicated to think about compared to a single version for the whole map in map.yml. When there is one XML file, it makes sense to track a global version, but when you have multiple XML files, this is another dimension that can create confusion.
Inconsistency in versioning mechanics, it's confusing if map makers use a common and required element to do the same thing in a different ways. In other words, there is simplicity in unity of purpose and how something is used. It's much simpler to understand "here is what this is, here is how to use it, look at any other map and you will see the same"
Ease of migration. A number of map makers are used to there being a version in map.xml and this confusion even extends to map admins who unnecessarily update this value even though it has no use. If the map.yml supported a semver, it could appear that we have migrated the semver from XML to map.yml. In fact, we have migrated the the version value that was in 'triplea_maps.yaml' (which is an integer), not the version value from XML. Not allowing a semver will help make it clear that this version value is not the deprecated version value that was previously found in XML.

djabwana

@LaFayette Thanks for thinking through this so thoroughly

This is still true- the vast majority of maps would still have a simple number that was incremented (and yaml wouldn't require it to be quoted) and people could use that widespread convention. I know as a professional software developer, I'm somewhat of the minority, but I had the opposite problem- I naively initially put a non-integer in assuming it would work and got a stack trace on deserialization.
I would argue that every version change is worth updating or else it wouldn't be worth a new version. If you want to track incremental progress you can use a feature branch and tag that or something. This does relate to the earlier points about partial download or the assets vs. spec thing you discussed, but conceptually, even a patch version is worth getting because something was fixed or changed
I'm 100% on the same page here. I'm only talking about a top level version in the new file. This is orthogonal IIUC to our discussion here
This is a good point - I think the best one out of the 5
I don't see this as significant- if they think the XML version got "promoted" to the "real" version and players get updates when it changes, that's great! that's exactly what we would want them to think

LaFayette

An ounce of prevention is worth a pound of cure, I'm happy to have the discussion if it leads to a better decision.

re: (3) & (5) the version values on different XML files are independent. If these values were 'promoted', what does it mean when one XML changes but not the other? How can there be a version change if one of the XML did not change? This is why it is kinda wierd to have multple independent game files with one version shared between them.

re: (2) there are some changes that are not worth bothering players with a download. For example removal of commented XML blocks. While I would agree that versioning should track all changes, this version number does have a practical use and we wouldn't want to both players with needless downloads. Consider also the case if map-admins were to bulk change maps for a cosmetic cleanup. If that accompanies a version bump, suddenly every player is prompted to update every map. Furthermore, if the version values are different across the board, then it is actually difficult for map adins.

That is another interesting use-case, let's say (6), if map admins needed to make a change across the board and have everyone update, it could be scripted to bump the version number. If that is ad-hoc per map, that script would be more difficult and it would not necessarily fit and break a map makers versioning scheme when it's suddenly updated to an arbitrary value (like zero).

djabwana

All of this discussion is assuming versions in the XML are going away - like you said it's deprecated. Only the version in map.yaml remains (right?). That's what I mean by "promoted"- all versions scattered across the XMLs have been removed and consolidated and promoted up to the root map.yaml (right?).

djabwana

@LaFayette r.e. point 6. I would argue if we automatically fix something for every map that doesn't actually change the game or its compatibiltiy (perhaps replacing isTwoHit for example) then the automatic script should not change the version and so we don't have worry about it.

If we do want to force everyone to update, say because isTwoHit was actually removed from the engine so we need to force it out or else the map would throw an error, then the script can add a suffix to everyone's version e.g. -hotifx-2.6, which is really great as a map maker because next time I check on my map I see that it's:
1.2.3-hotfix-2.6
that tells me that it's 1.2.3 which has meaning to me, but it was patched for engine 2.6 compatibility. I can now look up release notes for 2.6. That's way more helpful and meaningful to me than just seeing that my map went from 4 to 12.

r.e. "there are some changes that are not worth bothering players with a download. For example removal of commented XML blocks". This should just be a commit, not a version bump. Version changes should only track real/meaningful changes, not cleanup or superficial changes.

LaFayette

I think the version discussion boils down to utility vs complexity (specifically the complexity to understand and communicate how to use the map.yml version field).

There is a discussion open in github issues whether to bake categories into map.yml which would put it under map maker control and alleviate the map admin team from an ongoing upkeep task.

Deployment wise, remaining we'll need to generate a map.yml for every repo and upload it presumably to the top-most directory of each map. FWIW this should be not that bad, currently the map engine is now rigged to generate a map.yml file for any downloaded maps that do not have it, we'd only need to take the generated file and upload it.

Otherwise, does the current map.yml look good and is it clear? The XML path I think is maybe the most error prone and it's the path of any game XML relative to the map.yml file. If the map.yml file is at the top level of a map (expected), then the XML path is really just the path to the XML file from the map folder..

Last, hopefully it's also well understood that game and map name will now come from the map.yml file and the corresponding XML attributes would be considered deprecated and no longer read by 2.6+ engines.

The map.yml also removes the need for a map repository or map zip to have any kind of specific naming to match the map name in the XML, the map repo and zip could have any reasonable name and would essentially no longer matter.