Version management and coexistence

[Duplode]

Here go a few thoughts about handling different versions of the same car. I'll begin with a @dreadnaut quote from another thread:

You might note a version number there. The discussion above made me realise that we need to keep that explicit, because an old competition might want to point to a specific version of the car, and not to the most recent one. Versions can "branch", so it's not simple ordering. I think I'm roughly proposing WXYZ/<version-id> as a versioned car identifier.

This is a good capsule summary of what we'll have to deal with. Compared to the initial draft of the design in the GitHub repository, it also points -- rightly so, IMO -- toward more explicit version management. I'll also quote the relevant bits of the repo docs, just for the sake of providing contrast:

For each car:

• a <WXYZ>.yaml file containing
• [...]
• a resources directory containing all the car files
• an optional history directory, containing subdirectories for previous versions of the car

Such a layout would likely suffice for the happy path, in which cars always have a linear version history, the most recent release by the author is the default choice of version by the community, and there are no replay-incompatible releases once a car has been used in competition. History, though, has a way of playing tricks on us when we least expect.

One particular scenario I see as important to consider is that of a car having an initial release which is used in competitions and then, for whatever reason, gets a replay-incompatible update at a later point. It is worth noting this is not a theoretical concern: a few of Ryoma's cars which were picked up by competitions while he was away in 2022 later had performance-changing updates, most notably the Ferrari 641/2 featured in R4K last year.

With these considerations in mind, here's what, at the moment, I'd feel like adding to the repository layout for the sake of version management. This is a rough sketch, for the consideration and criticism of y'all:

• There should be an INI file for individual versions. There is no need to duplicate everything from the main INI file of the car, as the point is just providing clarity on what the version is. Plausible fields include:
  
  • car-id, for cross-referencing;
  • version-id, along the lines of what dreadnaut has suggested in the quote at the beginning;
  • release-date;
  • distributor (optional), who originally prepared the release. Relevant, for instance, to distinguish KyLiE's bugfix releases;
  • comment (optional), a one-line summary of what distinguishes the version.
  Additional information we might want to keep track of includes replay compatibility across versions, and known races in which a version was used. These are trickier, though, and can wait until we get the basics settled.
  
• All versions, including the default one, should get their own subdirectory and version INI file, ensuring uniformity of handling and documentation. (This differs from the initial GitHub draft, in which a privileged default version would have files in resources, while old versions would get subdirectories of history instead.)
• The main/default/current version should be recorded in a field of the car's INI file, so that tools and/or users can find the way to it. For the sake of convenience, it's likely we'll still want to provide the files of the main version outside of its subdirectory (e.g. as a zip in the car's root directory). I think it will be fine to replicate the files for that specific purpose.
  
  • Given the possibility of the version history splitting into branches, it might make sense to distinguish, with separate fields in the car's INI file, between the latest version by the author and the current community default (at least one of the fields being optional). The "community default" concept is perhaps similar to the notion of a "homologated" version (i.e. one that has been used in competition) that I tried to bring into the Southern Cross collection some time ago.

[dreadnaut]

Haven't had time to dig into this problem, but a couple of thoughts:

- release_date would be optional as well in my mind, the only requirement is "a version exists";

- I would keep information about all versions in the main INI file, for ease of both editing and processing; the front-end could filter and separate as needed.

[Duplode]

@dreadnaut Yup, both points make sense. The version release date should be optional indeed, as sometimes we'll just don't know. As for having the data for the versions in the main file, that may well be more convenient for what we'll be doing, and as you say the front-end can always split it off if we need that for some reason.

[Daniel3D]

Maybe split the ini into 3 sections.
- mandatory
- useful (mandatory if applicable)
- optional (the fun and interesting)

It sets a standard to work with, but doesn't restrict either.

[Cas]

Well, the good thing about files similar to these is that you can read what you want and ignore the rest. We just need to agree on default values.

[Daniel3D]

Well, the good thing about files similar to these is that you can read what you want and ignore the rest. We just need to agree on default values.

I know, but it's important to set a basic structure and some requirements so there is a equal base for all cars.