Requesting new handling of map change logs

[FrostionAAA]

Would it be possible to make a new standard regarding how map version change log info is accessible to the player?

Right now it seems some changelogs are written and viewed at the “download maps” part of tripleA, or in the “map notes”, or in a changelog.txt file in the map directory. There is no standard place to look for this information and get an overview of the map development. I would like to see map info gone from especially the game notes, the notes really only meant to help players play the map.

Would it not be possible for developers to make it so that players could click a button at the map selection screen and view change log info? Alternately or parallel to this, make it so that change log info could be accessible via the option in the in-game menu "help" where "Unit Help", "Game notes" and "About" are also located? Maybe these places could read from a change log file in the map directory? A file that the map makers should/could fill out with info. Maybe just a plain txt file with no fancy html code.

There are probably many versions of how map notes could be standardized. Maybe any selected option should take into account that not all maps have change logs at the moment. And that not all maps have map makers that will take action and make changelog files for their maps if this idea is realized.

I mentioned this idea at the developer forum here, and there are a few responses: http://tripleadev.1671093.n2.nabble.com/WORLD-AT-WAR-tp5862407p7592725.html

[RoiEXLab]

I like this idea and it reminds me of #453 Same question can be asked here... Would it be useful to show a Changelog window, when the player updates to a new map version?

And in general: Nothing is impossible in Terms of Code... the question is if it's worth the time...

[Cernelius]

Having a "Game Changelog" under "Game Notes" (instead of traditionally putting changelogs at the end of Notes, like you can see in NWO) would be surely a good thing (only "Game Notes" should be available as a side bar); both "Game Notes" and "Game Changelog" should be optional xml sections, not showing up if the section is left empty.

Other improvements may be having a "Game Rulebook" section separate from "Game Notes", in case some mapmakers want to provide a rulebook like the TWW one, but still having a hints section, and having "Skin Notes" and "Skin Changelog", separate from the xml ones, and recorded via notes.txt and changelog.txt, in the folder. These other improvements are likely marginal and chances are that they would be rarely used, and it might actually be confusing having so many different references ("Game Rulebook", "Game Notes", "Game Changelog", "Skin Notes", "Skin Changelog") in the same game.

But just splitting up the current "Game Notes" into "Game Notes" and "Game Changelog", as said, I think it would be worth it and clearly preferable.

Since it should be optional, mapmakers may still decide not having the "Game Changelog" section, or having the full changelog in the "Game Changelog" and still adding a short changelog at the end of "Game Notes".

Games exactly working by default TA rules (the ones explained in the TA rulebook) may have "Game Changelog" but not "Game Notes".

[DanVanAtta]

I'd like for us to make use of the map READMEs for this if possible. Perhaps an "Additional Game Notes.." button that opens a web browser to the maps README file. A map maker can edit their READMEs at any time and updates are live without a new map distribution or code change.

[Cernelius]

To me it seems very obvious what should be the first step.

The first thing first to do would be to add the xml a property name="changelog", that would be like the property name="notes", but not having a tab and displayed via a Help/Changelog button in the menu.

This would allow mapmakers to not have changelogs in Notes, while still being able to have it somewhere better than just buried inside the maps' folders.

I think the above is very agreeable and should be priority. Once that's done, the rest can still be discussed.

For example, I believe the WaW 2.0.2 Notes would be better without all the changelogs, but I don't feel like making changelogs totally inaccessible for normal users, by just burying them in the xml. A separate xml section for changelogs (displayed via the menu) is the obvious answer.

[DanVanAtta]

There are number of problems with the menu item route:

• A conditional menu is not ideal. Menu items are best when they are consistent between game types. But furthermore, the conditional logic in code is complexity that would be nice to avoid. Additionally, not only do we have a conditional branch, but we need to wire in data to make sure that the menu bar is aware of if a game has game notes or not. The latter part is relatively substantial work, but importantly it's not clean - it'll make the code even worse off than it is already.
• XML is not a good location for the game notes. There is already too much in the XML. All the content would need to be wrapped in a CDATA.. This content will make XML parsing and map download slower. The XML structure itself is not trivial and would require a number of updates. We would need at least two XML tags, one to wrap each game version, and another for the notes. Coupling the map versions with data in XML is not a good thing either, we are trying to get the versions out of the map XML. Also, the ordering of the change notes would not be guaranteed. For map makers, working on game notes would be relatively slow since the game would have to be re-launched to see any changes. Last, I'm not at all eager to support an in-game version of this feature. It's more stuff to test, and just more code..

On the other hand, putting the data on a README solves/avoids just about all of these problems and gives us the same benefit. The turn-around time is fast, there is a preview button in github to preview any changes. The in-game menu item would be consistent, and would always read the same "additional map notes". The code changes there would be very straight forward, we already have a 'give map feedback' button, so getting the URL of the README is easy.

Also to mention, we do not make good use of the map READMEs that come with each map repo for free, this is a good way to make better use of that. Fundamentally it is appropriate too, documentation about a map should be in the map's README. Game notes on how to play is fine being both in-game and on the readme, but for change notes, I do not see any reason to require that to be in-game, and a number of reasons why it is not desirable from a system/code point of view.

[Cernelius]

In which way would a menu displayed README based changelog work with reference to mods, meaning games referring to other map folders, and especially relatively to several mods part of the same folder, like: https://github.com/triplea-maps/ww2v3_variants or with reference to several xml (eventually of several different mapmakers) inside the same folder, like Sieg's "World_At_War" and ice's "World_At_War_1940" ?

p.s.: I still believe the changelog of a game should be part of the game itself, and in particular primarily of the xml, and secondarily of the skin, but this is just my point of view.

[DanVanAtta]

The menu would open up a web browser that would open the readme file, for example: https://github.com/triplea-maps/world_at_war, note that the readme there just says the map title. Presumably then the map readme could give links to skins.

Ultimately, skins do not really need much documentation. The handling of that via XML would be a very interesting question.. Which I think makes that approach yet even more complicated.

Mods, perhaps the README would be the README of the map. I think that would probably make most sense. then the mod can have a link back to the original map for reference.

[Cernelius]

@DanVanAtta I want to be sure we are not confusing the terms "mapskin" and "skin". With skin I (and I believe normally) mean whatever part of the map folder but the xml (not necessarily a not-original skin), which may either be the folder which the xml refers to (that may or may not be the one including the xml, and it usually is not for mods), as per property name="mapName", or a different one (in the first case, we would be talking of the original skin, which is the only skin available for most games). For example, if I change this unit: to this unit: while keeping the same image name, I'm making a skin-only change, that may be in the original skin or in some other skins. Original skins aren't supposed to be always the same either, as sometimes you may make a skin which looks better than the previous one, and they get swapped, like done for 270bc (this mapskin was the old original skin of 270bc https://github.com/triplea-maps/270bc-old_skin ) and proposed for napoleonic_empire. As I said, whatever changelog, also an external README or whatever, should be related primarily to the xml, not to the skin (= the folder except the xml). For example, when I say "skin", I also mean everything part of the "new_world_order" folder but what's inside the "games" folder (which is the original skin of the new_world_order.xml), not only the other alternative "new_world_order-..." skins (that are 100% skins, as being mapskins; that is maps without the "games" folders).

[DanVanAtta]

Skins/mods make the menu item approach even more complicated, it is even more reason to link out to a map repo's readme rather than putting the content in a game XML.

[Cernelius]

The simplest changelog case is when you are making a mod. In that case you are making xml only changes, not touching any skins. How the changelog of my whatever mod of whatisname is going to be recorded? Currently, I would put the changelog of my mod as part of the Notes, likely at the end of them (this is particularly critical for a mod, as I may want to show what's different from the original game (not necessarily the original or the current xml of the map) and, at the same time, explain stuff from start, especially with reference to people not knowing the other original game). As I said, keep in mind that my mod may share a folder with a plurality of other mods or even stay in the original skin, beside the main xml for the map. And also you should keep in mind that I may be making this mod for some time before uploading in github and in my changelog I want probably to record all changes made starting from the original modded xml, which may be the main xml for the map at some point (not necessarily the last current version) or yet another mod, which may in turn be a mod of another mod, etc., with all xml related changelogs summing up logically.

As I said, the only good solution is having two separate changelogs, one for the xml and one for the skin (normally, only the original skin, as mapskins are uncommon); of course, mods would have only the xml changelog, since mods are purely xml. Of course, when you make changes relevant for both the xml and the skin, you should record them in both changelogs, accordingly.

And, of course, the xml is primary and the skin is secondary. The fact that the github list is map based, not xml based (and you can have only one skin per map, either a normal map or a mapskin, while you can have from 0 to infinite xml per map), doesn't reverse this.

[DanVanAtta]

Good context. Though, multiple change logs, any of them optional, is yet even more complexity that would make this a difficult feature to build, and to get right. The README route seems to handle this easily, simply create a header section for each mod/skin with the relevant notes in those sections. There is one README per map repo, which maps to a single download. The README can then cover anything contained in that download, and/or link to arbitrary locations for further info.

If building something without a repo, whether you put those notes in a XML file, or a README file, is about equivalent. Though the preview option will not be there, but it's easy to find something to help you render markdown.

[Cernelius]

I definitively believe that the changelog of a map should be bundled with the map itself.

If you want the changelog being related to the skin, instead of to the xml (which is clearly very wrong, in my opinion), as this is what would be if you would have the README as the changelog reference, then you should rather have a "changelog.txt" inside the map's folder, that gets opened and read via the Help menu.

Not a good solution, because then all of the various mods referring to a same map would have the same changelog (and you would have different changelogs for different skins (the original maps and the mapskins) of a same game), but surely better than referring to the README or anything external.

I can anticipate mapmakers would prefer having their changelogs somewhere inside their maps, and this thing of using the README is likely to just create an easily confusing duplication of changelogs, where mapmakers will record them both somewhere inside the maps' folders as well as in the related README, for display purposes.

If the firs best solution of having the changelog as a simil-Notes section inside the xml itself is not advisable from a code perspective, then my second best solution would be to have a changelog.properties inside the map folder, and this changelog.properties being somehow coded so to support different changelogs for different xml, showing up partially, in a similar way as the objective.properties, in which you have something like this:

World_War_II_v3_1941.Germans;objectiveAttachment2=+5 PUs if Axis control 3 of Baltic States, East Poland, Ukraine, East Ukrain, and Belorussia World_War_II_v3_1941.Germans;objectiveAttachment3=+5 PUs if Axis control Karelia or Caucasus

World_War_II_v3_1941.Russians;objectiveAttachment1=+5 PUs if Soviets control Archangel and no allied forces in Soviet controlled territories World_War_II_v3_1941.Russians;objectiveAttachment2=+10 PUs if Allies control 3 of Norway, Finland, Poland, Bulgaria, Czechoslovakia, and Balkans

World_War_II_v3_1941.Japanese;objectiveAttachment1=+5 PUs if Axis control Manchuria, Kiangsu, and French Indo China World_War_II_v3_1941.Japanese;objectiveAttachment2=+5 PUs if Axis control 4 of Kwangtung, East Indies, Borneo, Philippine Islands, New Guinea and Solomon Islands World_War_II_v3_1941.Japanese;objectiveAttachment3=+5 PUs if Axis control 1 of Hawaiian Islands, Australia, or India

World_War_II_v3_1941.British;objectiveAttachment1=+5 PUs if Allies control any territory originally controlled by Japan World_War_II_v3_1941.British;objectiveAttachment2=+5 PUs if Allies control E Canada, W Canada, Gibraltar, Egypt, Australia and South Africa World_War_II_v3_1941.British;objectiveAttachment3=+5 PUs if Allies control France or the Balkans

World_War_II_v3_1941.Italians;objectiveAttachment1=+5 PUs if Axis control 3 of Egypt, Trans Jordan, France, and Gibraltar World_War_II_v3_1941.Italians;objectiveAttachment2=+5 PUs if Axis control Italy, Balkans, Morocco and Libya AND no enemy surface ships in sea zones 13, 14, or 15

World_War_II_v3_1941.Americans;objectiveAttachment1=+5 PUs if Allies control France World_War_II_v3_1941.Americans;objectiveAttachment2=+5 PUs if Allies control Philippine Islands World_War_II_v3_1941.Americans;objectiveAttachment3=+5 PUs Allies control W U.S., Central U.S., and E U.S World_War_II_v3_1941.Americans;objectiveAttachment4=+5 PUs if Allies control 3 of Midway, Wake Island, Hawaiian Islands, and Solomon Islands

World_War_II_v3_1942.TABLEGROUP.01;Japanese=objectiveAttachment1;objectiveAttachment2;objectiveAttachment3 World_War_II_v3_1942.TABLEGROUP.02;Russians=objectiveAttachment1;objectiveAttachment2 World_War_II_v3_1942.TABLEGROUP.03;Germans=objectiveAttachment1;objectiveAttachment2;objectiveAttachment3 World_War_II_v3_1942.TABLEGROUP.04;British=objectiveAttachment1;objectiveAttachment2;objectiveAttachment3 World_War_II_v3_1942.TABLEGROUP.05;Italians=objectiveAttachment1;objectiveAttachment2 World_War_II_v3_1942.TABLEGROUP.06;Americans=objectiveAttachment1;objectiveAttachment2;objectiveAttachment3;objectiveAttachment4

World_War_II_v3_1942.Germans;objectiveAttachment1=+5 PUs if Axis control France, NW Europe, Germany, Czechoslovakia, Bulgaria, and Poland World_War_II_v3_1942.Germans;objectiveAttachment2=+5 PUs if Axis control 3 of Baltic States, East Poland, Ukraine, East Ukrain, and Belorussia World_War_II_v3_1942.Germans;objectiveAttachment3=+5 PUs if Axis control Karelia or Caucasus

World_War_II_v3_1942.Russians;objectiveAttachment1=+5 PUs if Soviets control Archangel and no allied forces in Soviet controlled territories World_War_II_v3_1942.Russians;objectiveAttachment2=+10 PUs if Allies control 3 of Norway, Finland, Poland, Bulgaria, Czechoslovakia, and Balkans

World_War_II_v3_1942.Japanese;objectiveAttachment1=+5 PUs if Axis control Manchuria, Kiangsu, and French Indo China World_War_II_v3_1942.Japanese;objectiveAttachment2=+5 PUs if Axis control 4 of Kwangtung, East Indies, Borneo, Philippine Islands, New Guinea and Solomon Islands World_War_II_v3_1942.Japanese;objectiveAttachment3=+5 PUs if Axis control 1 of Hawaiian Islands, Australia, or India

World_War_II_v3_1942.British;objectiveAttachment1=+5 PUs if Allies control any territory originally controlled by Japan World_War_II_v3_1942.British;objectiveAttachment2=+5 PUs if Allies control E Canada, W Canada, Gibraltar, Egypt, Australia and South Africa World_War_II_v3_1942.British;objectiveAttachment3=+5 PUs if Allies control France or the Balkans

World_War_II_v3_1942.Italians;objectiveAttachment1=+5 PUs if Axis control 3 of Egypt, Trans Jordan, France, and Gibraltar World_War_II_v3_1942.Italians;objectiveAttachment2=+5 PUs if Axis control Italy, Balkans, Morocco and Libya AND no enemy surface ships in sea zones 13, 14, or 15

World_War_II_v3_1942.Americans;objectiveAttachment1=+5 PUs if Allies control France World_War_II_v3_1942.Americans;objectiveAttachment2=+5 PUs if Allies control Philippine Islands World_War_II_v3_1942.Americans;objectiveAttachment3=+5 PUs Allies control W U.S., Central U.S., and E U.S World_War_II_v3_1942.Americans;objectiveAttachment4=+5 PUs if Allies control 3 of Midway, Wake Island, Hawaiian Islands, and Solomon Islands

And only the lines starting with "World_War_II_v3_1941." are shown in the relative game, etc..

That would be fine for showing changelog xml related in a proper way, and the only limit from having it right inside the xml is that modmakers need to update the changelog.PROPERTIES inside the referring folder too.

My third best solution, as said, would be having a changelog.txt, inside the main map folder, working just like you propose for the README; just being inside the maps, instead of external.

Since me and @DanVanAtta are monopolizing the discussion, apparently, mostly just reproposing our views, would be interesting to know what other people (especially developers) think as well...

[DanVanAtta]

If someone wants to put release notes in the game notes, I suppose they are welcome to. Otherwise I don't see people inventing a spot to duplicate their release notes between the README and the other spot they find.

If you check out the file structure of a map repo: https://github.com/triplea-maps/world_at_war, notice that the README is grouped together with the other files. With recent changes, map makers should be using the file/folder structure of the repo to develop maps, avoids all the zipping/unzipping work.

I'm afraid to say the properties file approach is even more challenging than an XML based approach. In the properties file, just like XML, there is no guarantee of ordering. Every property would need to be prefixed with the version number, there would be a lot of duplication, and this would require custom parsing rules.

Similar if a text file is displayed from the game, there would be no formatting applied, and chances are it would look terrible.. Plus, in the above two approaches, there is no easy way to preview the work.

@Cernelius , what other objections do you have to the README file? It seems you're stuck on the idea of the notes being available in-game only. I think we can easily drop that idea, we have plenty of content that opens in new web browsers. Ultimately the external README I really see as the cleanest solution to this:

• map makers can preview changes immediately
• README markdown is simple, simpler than XML
• map makers can put notes in pre-release maps there, which is particularly useful if say someone is checking out pre-release map versions
• from a game engine point of view it is quite simple

Ultimately, any of the in-game approaches is going to require a good bit of code, and would only be useful for the very few maps that build out a change log of their own. We've 100+ maps, I suspect we're only going to have 2 or 3 that have the time taken to build a change log notes. For that same effort, may as well put the data in README, which would be doubly helpful if someone is browsing the map repos.

In fact, that is a use-case which has been omitted from this discussion. If you're looking at maps from github, having a well developed readme would be very useful.

[Cernelius]

I've no other objections.

[DanVanAtta]

Summarizing a bit, the README approach has a number of clear advantages:

• more flexible (can include images, no fixed format requirements)
• has a preview capability, less error prone
• can be seen before a map is released
• does not add to the download weight of the map
• least coding effort, cleanest integration

@FrostionAAA , as another map maker, do you have any thoughts on if change notes are put in the maps readme, rather than creating a special feature to support it? Here is an example of such a README file (note, they come standard with all map repos, and are currently not well used) - https://github.com/triplea-maps/world_at_war/blob/master/README.md)

[FrostionAAA]

Well, my thoughts are that that change logs should have info on the history of the map, and therefore it would make very much sense to have a change log button besides the "give feedback".

In addition to that place, it would make much sense to also be able to view the change log while playing or waiting for your turn. I would like to see change log keep away from notes and xml as well as kept away from the area under the minimap. And I think we could consider that many change logs are and will be empty. Therefore I don't think it will make sense to have change log under minimap while playing. I would suggest a playing player could view change log by going to the ingame "Help" menu. There is already a "Unit help", "Game notes" and "About (this map)" there.

It would make sense for the change log button and link to get the info from only one place. Also, I think we can not expect map makers to engage themselves with and learning anything about Github and file managing there. It is hard enough to figure out how to construct a map. Few people get to the point where they have made maps or mods to be released, and my prediction is that fewer will try to learn Github. For that reason first time oploads and map updating should continue to be allowed at the forum. And also for that same reason any change log file would probably be best placed in the map zip / directory.

To make map makers aware of keeping a change log info file, the file could be mandatory (while still being able to be empty) and maps could give error logs if missing from the map directory. To start this process, could a Github bot add an empty change log file to all maps for map makers to edit, while new TripleA engines could require offline maps in development to add the file?

[DanVanAtta]

@FrostionAAA , I mostly agree, and an external web browser with the same information vs a Java Swing window seems to accomplish every goal stated.

Except, I do disagree here:

It would make sense for the change log button and link to get the info from only one place. Also, I think we can not expect map makers to engage themselves with and learning anything about Github and file managing there. It is hard enough to figure out how to construct a map. Few people get to the point where they have made maps or mods to be released, and my prediction is that fewer will try to learn Github. Fore that reason first time oploads and map updating should continue to be allowed at the forum. And also for that same reason any change log file would probably be best placed in the map zip / directory.

• Map making today is REALLY difficult. It is nothing compared to the drag and drop of github, or clicking a pencil icon to edit a file. If a person can hack the XML of a map, and all the related problems, then the github part is nothing.. Effectively github today is a file hosting service, and requires zero command line.
• Long term, the map admin responsibilities need to continue shrinking. Pretty soon we'll be in a spot where instead of map zips, map makers will provider a map folder that is in the right format that can be uploaded directly.

"To make map makers aware of keeping a change log info file, the file could be mandatory (while stil being able to be empty) and maps could give error logs if missing from the map directory. "

This point I do not think is reasonable. A) we'd have to update every map to have an empty file - what is the point in that? Plus, it's a lot of work already. B) The 'special' release notes file illustrates some of the code complexity problems. We'd have to have a format for it, people would have to get it right, error parsing for handling when people do not, and general handling of the file to parse it and deal with the data in-game, and rendering. Every map repo today has an optional README.md file, it's effectively exactly what is being asked for - a place where you can add additional map notes/information, which can include change notes if you wish.

[FrostionAAA]

Well, the README.md at every map’s Github location is not a bad alternative, and it could still fit in with most of my other ideas. The single most important thing that I request is somewhere to post/read some change log info, preferably when downloading a new versions of maps/mods.

[DanVanAtta]

@FrostionAAA , any changes or latest thoughts on what you would like done?

The github README I still think is a good first approach. We could as a next step update the game engine to scrape the README and display key parts of it as the download description.

[FrostionAAA]

No. It sounds like a good idea, and people have easy access to edit the github README if needed.

[DanVanAtta]

@ron-murhammer @ssoloff @simon33-2 @RoiEXLab kindly note above the decision to use README.md files on map repositories for map change logs. I think there is flexibility on the exact file, but using README.md is a double whammy since you get documentation when browsing the repo, and you also can do automated scraping for map description. I updated the feature backlog to reference this: https://github.com/triplea-game/triplea/wiki/Feature-Back-Log