Adding versioning to schema?

[chrisalleng]

A common problem with parsing through tournament data and stats is lack of versioning for when points are used. Especially around the times points are updated, event organizers often specify that points updates after XYZ date are no longer valid, but it's effectively impossible to store that data, so effectively there are many lists that appear illegal or like junk, despite being legal in the previous points cycle. This would allow for things like pulling lists from listfortress with specific versions, for example:

Current example: {"faction":"galacticrepublic","pilots":[{"id":"anakinskywalker-btlbywing","ship":"btlbywing","points":6,"upgrades":{"force-power":["shatteringshot"],"turret":["ioncannonturret"],"torpedo":["protontorpedoes"],"astromech":["r4pastromech"],"modification":["afterburners"]}},{"id":"obiwankenobi-eta2actis","ship":"eta2actis","points":5,"upgrades":{"force-power":["patience"],"talent":["marksmanship"],"cannon":["autoblasters"],"astromech":["r7a7"]}},{"id":"ahsokatano","ship":"delta7aethersprite","points":4,"upgrades":{"force-power":["compassion"],"astromech":["c110p"],"configuration":["calibratedlasertargeting"]}},{"id":"barrissoffee","ship":"delta7aethersprite","points":3,"upgrades":{"force-power":["instinctiveaim"],"missile":["concussionmissiles"],"configuration":["calibratedlasertargeting"]}},{"id":"contrail","ship":"nimbusclassvwing","points":2,"upgrades":{"configuration":["alpha3bbesh"]}}],"points":20,"vendor":{},"version":"2.5.0"}

Suggested example: {"faction":"galacticrepublic","pilots":[{"id":"anakinskywalker-btlbywing","ship":"btlbywing","points":6,"upgrades":{"force-power":["shatteringshot"],"turret":["ioncannonturret"],"torpedo":["protontorpedoes"],"astromech":["r4pastromech"],"modification":["afterburners"]}},{"id":"obiwankenobi-eta2actis","ship":"eta2actis","points":5,"upgrades":{"force-power":["patience"],"talent":["marksmanship"],"cannon":["autoblasters"],"astromech":["r7a7"]}},{"id":"ahsokatano","ship":"delta7aethersprite","points":4,"upgrades":{"force-power":["compassion"],"astromech":["c110p"],"configuration":["calibratedlasertargeting"]}},{"id":"barrissoffee","ship":"delta7aethersprite","points":3,"upgrades":{"force-power":["instinctiveaim"],"missile":["concussionmissiles"],"configuration":["calibratedlasertargeting"]}},{"id":"contrail","ship":"nimbusclassvwing","points":2,"upgrades":{"configuration":["alpha3bbesh"]}}],"points":20, "pointsversion":"2.5.1","vendor":{},"version":"2.5.0"}

Similarly, we could use this versioning in listfortress itself in event details to distinguish what events were run with what points.

Example use case: Richmond Open is an event planned for May 27th-29th. AMG has stated there is a points update coming on or before the 27th, so when this data is imported into ListFortress, it will not have the context that despite being after the release date of points. Anyone attempting to use this data will potentially need to infer that it was played with out-of-date points.

Similarly, if the points update happens on say May 25th, players at events will be unable to use squad builders for the event itself, since they will have been updated to latest points. Having a repository of all previous points/upgrade slots as part of the XWS spec itself may allow for easier support for squadbuilders to support different point values as well.

[doweaver]

Given that I don't believe the official documents have version numbers, but instead an "effective date", should that be considered as the unique identifier, to avoid any potential confusion around what "2.5.1" means? Or is there an honest-to-god version number I'm not seeing?

Worth considering additionally a pointsSource attribute? Just using a version number/effective date wouldn't cleanly allow for something like a builder for a custom event that uses some other method of points. Maybe not necessary, just thinking about future-proofing.

[chrisalleng]

You're right, there is no official versioning. But, we often get effective date overlap, especially when they push out smaller changes. I'm not sure it's worth preserving the mistakes that tend to only stay up for a couple of days, but if I remember correctly in the last few points changes we have 2-3 different minor versions, all with the same effective date. We'd have to create a master versioning number/system system accordingly to avoid that, if everyone else is concerned about it as well.

By points source, do you mean for allowing some API that could be hosted to access points directly in realtime used by other services like squadbuilders etc? Or for custom rulesets, like for one off tournament rules with different points, etc? I think both are pretty valid, but wasn't sure which you meant!

[doweaver]

You're right, there is no official versioning. But, we often get effective date overlap, especially when they push out smaller changes. I'm not sure it's worth preserving the mistakes that tend to only stay up for a couple of days, but if I remember correctly in the last few points changes we have 2-3 different minor versions, all with the same effective date. We'd have to create a master versioning number/system system accordingly to avoid that, if everyone else is concerned about it as well.

The small mistakes that get ironed out actually make me more in favor of using "effective date" as the versioning, I think :D If we're using ~semantic versioning, it's not clear whether those mistakes should/would be preserved (at least to me), whereas if you're using "effective date" versioning, I think it's pretty obvious they shouldn't be (effective date 3/01/2022 is the "latest state" of everything on that effective date). This assumes that we don't get anything other than a few minor mistakes fixed soon after an effective date doc, which... I think is the case? But I'm not positive?

By points source, do you mean for allowing some API that could be hosted to access points directly in realtime used by other services like squadbuilders etc? Or for custom rulesets, like for one off tournament rules with different points, etc? I think both are pretty valid, but wasn't sure which you meant!

I was thinking of the second. The specific example that came to mind was the REMEMBER THE GOOD TIMES tourney, where every ship was at its lowest historic price point. I don't think there's really any way to support that without some special "other" source of points. That said, an API that folks can call to get points for certain versions does seem like the sort of mature service that would be really useful...

One other thing - I'm realizing that "points*" is a bit of a misnomer, given that the version also includes loadout values, slots, and keywords... but given that that misnomer is sort of enshrined by AMG calling it a "points document", I guess that's probably an upstream issue that's not worth fretting about :)

[chrisalleng]

Actually, slight correction. It seems like there is an official numbering system, but it's extremely opaque. The filename for the latest points document is: SWZ_Ship_Points_1.4.1.pdf. I'm having trouble finding previous versions of the documents, but would be great to have as a reference to see if it's something we could actually use or if it is not going to be maintained well.

The small mistakes that get ironed out actually make me more in favor of using "effective date" as the versioning, I think :D If we're using ~semantic versioning, it's not clear whether those mistakes should/would be preserved (at least to me), whereas if you're using "effective date" versioning, I think it's pretty obvious they shouldn't be (effective date 3/01/2022 is the "latest state" of everything on that effective date). This assumes that we don't get anything other than a few minor mistakes fixed soon after an effective date doc, which... I think is the case? But I'm not positive?

I somewhat agree with this, but, it seems like a large amount of confusion could/would come from these, as the effective dates listed in the documents have historically not lined up very well with the actual date they're released. From both AMG/FFG we've commonly gotten documents listed that came into effect the prior month. If I'm creating some interface, which one of these is less confusing to pick when users are trying to pick a points version?

1.4.1 (Released 24 Feb 2022) 1 Mar 2022 (Released 24 Feb 2022)

[doweaver]

Actually, slight correction. It seems like there is an official numbering system, but it's extremely opaque. The filename for the latest points document is: SWZ_Ship_Points_1.4.1.pdf. I'm having trouble finding previous versions of the documents, but would be great to have as a reference to see if it's something we could actually use or if it is not going to be maintained well.

Oh, neat! That seems like the best option, assuming that AMG remembers to increment the versioning, which... I would THINK they would 😅

1.4.1 (Released 24 Feb 2022) 1 Mar 2022 (Released 24 Feb 2022)

Do we really care what day it was released? I guess there would potentially be confusion for tournaments played on Feb. 26... but then, theoretically those lists should have the pointsVersion embedded and pointing to "1 Mar 2022".

[doweaver]

Maybe the real answer is we don't trust AMG enough to do either dates or versions with any consistency and each points environment gets a GUID identifier and gets decorated with metadata like version number and effective date... but I think that requires some additional engineering to maintain, obviously... probably too much :)

[chrisalleng]

Do we really care what day it was released? I guess there would potentially be confusion for tournaments played on Feb. 26... but then, theoretically those lists should have the pointsVersion embedded and pointing to "1 Mar 2022".

I think so? At least I do, one of the main cases something like this would be to fix is the confusion around those edge cases. I think you're right that it could be mostly fixed by just using the effective date in whatever dropdown and not listing the release date at all, but I can already see the bug reports coming in for something like metawing saying "i chose march 1 points but tournaments in february showed up".

Maybe the best course of action is to see what happens with the next points update? It's coming in a few weeks, and it's not like any of this would be done by the time those release anyways. Most of the interesting/hard work is only possible once we have multiple versions of points regardless!

[doweaver]

That makes sense to me! And the truth of it is as long as the historical points are being recorded, the id/reference that gets used seems like it should be pretty easily updateable in the future.

Oh, they stopped adding IDs, so let's use dates.

CTRL+F for the four IDs we have and replace with those dates

[danrs]

Sounds like a good idea. I’ll just add that this repo often has incremental error corrections as we notice problems with it, and we need to do a new “release” tag on GitHub to make vassal pick up any changes. So we will need some kind of semantic versioning scheme because list fortress won’t care about bug fix level version changes, only “new points” or “new ships” level of changes

[chrisalleng]

I've been thinking on this more. Any thoughts? Starting to think the only user of this historical data would be me so seems silly to build out a huge standard for it for everyone to have to deal with, but curious if others have a desire/want for it.

[danrs]

I think it's a decent addition but agree it has limited utility. Most people don't really care about old points values and old events - it's usually enough just to look at the lists used and not worry about the points tallies.

How would you handle changes in squad building logic? Not just points changes but something like the 2.0->2.5 shift

[chrisalleng]

I'm thinking of something like an array of dates/versions with associated costs/loadouts? Basically something like this:

[ { "2.0.1": 47 }, { "2.0.2": 49 }, { "2.5.1": { "cost": 5, "loadout": 10 } } ]

With a reference of versions to dates somewhere as well.

[doweaver]

Let's see - so as things stand now, you'd need:

• squad points
• loadout value
• slots
• keywords (maybe not, if there's no precedent for change)
• ...anything else?

[danrs]

Including all that information on every pilot could be quite cumbersome for us maintainers, but I’m not sure where else to store it. I also hope that they don’t change squad building again and make us change the logic…

On Tue, 16 May 2023 at 11:39 am, Doug Stone-Weaver @.***> wrote:

Let's see - so as things stand now, you'd need:

• squad points
• loadout value
• slots
• keywords (maybe not, if there's no precedent for change)
• ...anything else?

— Reply to this email directly, view it on GitHub https://github.com/guidokessels/xwing-data2/issues/542#issuecomment-1548929899, or unsubscribe https://github.com/notifications/unsubscribe-auth/ABLOVLOVR2UWAQI6YI7XG6TXGLZI3ANCNFSM5VDC4GKQ . You are receiving this because you commented.Message ID: @.***>

[chrisalleng]

Let's see - so as things stand now, you'd need:

• squad points
• loadout value
• slots
• keywords (maybe not, if there's no precedent for change)
• ...anything else?

At a high level, basically what I think we'd want is an array of all previous versions of the ship. There are also things like errata to worry about, so I almost think just having like an "oldversions" name that's a key value pair with an ID for some specific points date/update, then the entire body of the json of each pilot at that particular point in time.

It would be a lot of storage for each and every pilot, and to @danrs point the schema for maintenance would be a nightmare as well. I think it's safe to say this probably falls outside the scope of XWS, and a fork/extension would probably be the "correct" implementation of something like this. I was thinking we could do something "simple" like just maintain a list of point/slot changes, but it wouldn't fit anywhere in XWS that makes any sense without a giant framework.

[doweaver]

Here's maybe a really dumb thought, because my experience using tags and releases in Git is nonexistent, but can we handle this with Git tags? Like, tag whatever commit with that version number version, and then consumers could (if they wanted) potentially pull from those commits? It feels a little funky to have to clone the repo multiple times to get multiple versions, but you get full versioning with almost no additional maintenance cost, and the cost to utilize it doesn't seem much worse than it would be to have it as a "native" concept...

[chrisalleng]

Hah, I never thought of that, but it's probably the least bad solution of all the suggested changes. Yes, there will be some mistakes mistakes and such effectively immortalized, and a lot of image references will be wrong, but it's all in the history perpetually.

Maybe the better solution is to make a branch of each "version" of points, that can be up to date with correct images and such? Could even use the github releases versions to have clear labeling of them as well, and then we can fix issues with each branch separately without breaking other things.

[danrs]

I think that’s a good idea as well. The only issue will be if there isn’t a clean commit that lines up with a each past version. If we are lucky then there should be, probably? Then all we have to do is go back and add tags to this repo for points versions.

If not, you could fork this repo and create a branch which just has a commit for each points revision but that would involve more messing about with git commands

On Wed, 17 May 2023 at 1:24 am, chrisalleng @.***> wrote:

Hah, I never thought of that, but it's probably the least bad solution of all the suggested changes. Yes, there will be some mistakes to be corrected along the way, and a lot of image references will be wrong, but it's all in the history.

Maybe the better solution is to make a branch of each "version" of points, that can be up to date with correct images and such? Could even use the github releases versions to have clear labeling of them as well.

— Reply to this email directly, view it on GitHub https://github.com/guidokessels/xwing-data2/issues/542#issuecomment-1550077327, or unsubscribe https://github.com/notifications/unsubscribe-auth/ABLOVLJAISE6XZZWXVKNOZTXGOZ5VANCNFSM5VDC4GKQ . You are receiving this because you were mentioned.Message ID: @.***>

[chrisalleng]

I think it's safe to say we don't have the manpower for this now. Maybe later down the road it's worth taking a look at, but that time isn't now