[Spec] Come up with a versioning strategy

[Baklap4]

Suggestion

Currently the spec is unversionized. This comes with a couple of complications and prevents us from easily adding more features without disrupting everyones hard work, time and effort.

With versioning of the specfile we should be able to minimize the impact and be able to prepare users and creators for new things to come.

Use case

Currently there are tens of thousands of txt out there roaming in the wild. These are made with best effort intentions but differ a lot when taking a closer look.

Then for the consuming parties (karaoke programs, and creator software) need to somehow interpret the tags and notetypes. By categorizing them into a couple of versions we can differentiate txtfiles out there and upgrade them when we find them to adhere to the spec.

Extra info/examples/attachments

This issue is to come up with a versioning strategy. We'll use this to dump our brainfarts and gather info on how to tackle this problem. At a later stage we're going to implement it if we have an idea on how to progress into solidifying the spec.

[Baklap4]

My personal strategy would be what i've already posted within Discord:

1. Create a bare minimum specification of tags and note types we need in the format (this is the "undefined" format which currently every txt file is)
2. Create a 1.0.0 specification supporting every tag and note-type we currently have
3. Define new features and talk about how to implement them in a new ultrastar format specification and how clients and writers should interpret those.

Songs that traverse from Undefined to 1.0.0 will be updated in the respective host (USDB, ultrastar-es, mylittlekaroke, etc). From there it can be improved upon by adding new features etc.

For this to work we'll need an extra tag within the txt file to state the version. If this tag is not there it's in the undefined category.

If possible, after we decided a versioning strategy, i'd like to work together with hosting sites (Alex from USDB, and TeLiXj from Ultrastar-es) to somehow enforce this tag upon upload.

[marwin89]

This sounds reasonable to me. I agree.

[marwin89]

Hi @achimmihca, @bohning , @rakuri255, @basisbit , @barbeque-squared,
what do you think about versioning strategy of @Baklap4 ? I agree to that.

[barbeque-squared]

From there it can be improved upon by adding new features etc.

I would like some more deliberation on the "etc." part of this, specifically when it comes to breaking changes, as well as how many (major? patch? bugfix?) versions older than the most recent one an application is supposed to be able to read? (I think writing in whatever is the newest version is fine)

I see two categories of things that we might want to deprecate/remove/break at some point:

• Stuff like #RELATIVE, or streamlining the myriad of tags that currently use a mix of milliseconds and seconds, or comma vs dot. This is breakage that isn't hard to fix automatically.
• Difficult stuff: variable BPM, #VOCALS (I think it's called like that), P3 that will usually result in manual txt edits.

NB: please don't discuss the tags in here, I'm using them as examples to get a point across.

The first one, I'm pretty sure we can come to some common sense when versioning things. These also aren't the most obnoxious things to have to keep supporting for a while in an older form anyway.

The second one is the issue. Currently we're already arguing about at least one of them whether it should be supported in the "undefined" version or not. This will get a million times worse if it makes it into 1.0.0. How long would I (as a developer) have to keep supporting something if it makes it into 1.0.0 and we deprecate it in, say, 1.1.0?
Because if the answer is going to be "essentially forever", then what incentive is there for me (as a developer) to ever want to start versioning things in the first place?

(USDX especially is littered with features and things that are relevant for maybe 1% or 0.1% of its users. I'm already having a hard enough time getting rid of those and I don't doubt leakage has occured into the txt's)

[Baklap4]

Yoo @barbeque-squared

I would like some more deliberation on the "etc." part of this, specifically when it comes to breaking changes, as well as how many (major? patch? bugfix?) versions older than the most recent one an application is supposed to be able to read? (I think writing in whatever is the newest version is fine)

How long a version should be supported is always a question, the best approach -which is also stated by the semver docs- for this would be to deprecate an item in a minor release and then introduce a new major version for completely removing it

How should I handle deprecating functionality?
Deprecating existing functionality is a normal part of software development and is often required to make forward progress. When you deprecate part of your public API, you should do two things: (1) update your documentation to let users know about the change, (2) issue a new minor release with the deprecation in place. Before you completely remove the functionality in a new major release there should be at least one minor release that contains the deprecation so that users can smoothly transition to the new API.

From: https://semver.org/#how-should-i-handle-deprecating-functionality

For example:

1. version 1.0.0 introduces feature "foo"
2. version 1.1.0 deprecates "foo"
3. version 2.0.0 deletes feature "foo".

So it depends on which kind of developer you are...

• If you're a creator program you should always try to aim the latest version, and not be using any deprecated tags. As you're the source of the problem
• If you're a hosting site you should support pretty much all of it to eternity untill all songs have moved to latest. With usdb this can be pretty easy to do when we can post to usdb through usdb-syncer. However if a version is so minimal available they also should remove it as they are distributing the problem
• If you're a karaoke program you should at least support the last major with optional "extra" support for earlier versions

It's a problem which kind of fixes itself through enough time i think. Hosting sites can post analytical info about versions distributed, and karaoke / creator programs can use this info again to determine what to actually support. And say for example that if version 1.1.0 is not found anymore in 10-20% of the songs that they can start removing the feature

The second one is the issue. Currently we're already arguing about at least one of them whether it should be supported in the "undefined" version or not. This will get a million times worse if it makes it into 1.0.0. How long would I (as a developer) have to keep supporting something if it makes it into 1.0.0 and we deprecate it in, say, 1.1.0?

I think i've answered this above

Because if the answer is going to be "essentially forever", then what incentive is there for me (as a developer) to ever want to start versioning things in the first place?

The answer as always is it depends, but forever shouldn't be the goal as this would defeat the purpose of versioning. Like i said before we can use analytical data from hosting sites to determine when to remove a certain feature. And if this data can't be produced by the hosting sites i can create a cronjob to traverse the complete library which gets auto-updated every day as i'm probably one of the few people to have all the data available

Ending words...

I might be kind of optimistic about it and yes i know it comes with a lot of collaberation effort from all sites. But seeing the progress this repository already made i think people are old and wise enough to actually do this as it comes with almost zero extra effort from the creators point of view

[achimmihca]

I also think that semver makes a lot of sense for this.

For this to work we'll need an extra tag within the txt file to state the version

I agree again, a #VERSION tag might be helpful to determine how the rest of the file should be parsed.
Preferably, it should be one of the first tags because parsing of other tags may depend on this (e.g. time units).

[marwin89]

this looks like we have a consens here. @basisbit @bohning @rakuri255, @AlexanderS do you agree?

[marwin89]

SUMMARY

So here is a summary for this issue up till now.

1. Our versioning strategy for UltraStar Song Format specification is based on semantic versioning SEMVER.
2. We deprecate features in minor versions.
3. We remove features in major versions.
4. We add features in minor versions.
5. We are optimistic about collaboration.
6. We expect this following co-working beheaviour from all parties:

Roles / Behaviour	Who	To-Do
Creator Software	Karedi, YASS Reloaded, USDB-SYNCER, UltraSinger, UltraStar Manager	Aiming for the latest version, so new songs are automatically up to date
TXT-File-Hosting	USDB.animux Admins	Boost all online files to the latest released version, most are at least v0.3.0 and are easy to upgrade to v1.0.0
Games	UltraStar Deluxe, Melody Mania, Performous, Vocaluxe, My Little Karaoke, etc.	Generally: support latest version and latest version - 1. But beginn with: v1.0.0 - usdb will update txt-files fast to v1.0.0 with the help of automation
Enduser	players, song creators, song manager	Load new songs via USDB-SYNCER, stay in sync with usdb

7. We make this stragety transparent on our website usdx.eu/format

[marwin89]

2nd SUMMARY / VOTE NOW 📈 ✋

So here is the second summary for this issue (considering some discord discussion in ultrastar creators community too @basisbit ).

Please vote for this issue till 15th nov 2023 with emoticon 🎉 / 🚀 / ❤️ .

There are three approaches about versioning strategy in our discussion:

🚀 A: Clear Semantic Versioning SEMVER [v1.1.0]

• What: deprecating and add in minor versions, remove in major versions.
• Advantage: smooth transitioning, official international standard, understood by devs and tools (breaking changes)
• Disadvantage: not understandable for players

🎉 B: Use YEAR for Versions without SEMVER [v2023]

• What: deprecating and adding in major versions, no minor versions
• Advantage: simple and easy to understand for players
• Disadvantage: no standard, its not obvious if theer are addings, removals or breaking changes

❤️ C: Use YEAR and only major versions [v2023.0.0]

• What: deprecating and adding in major versions, no minor versions
• Advantage: simple and easy to understand for players
• Disadvantage: no standard, its still not obvious if there are addings, removals or breaking changes

---

details A 🚀:

1. Our versioning strategy for UltraStar Song Format specification is based on semantic versioning SEMVER.

2. We deprecate features in minor versions.

3. We remove features in major versions.

4. We add features in minor versions.

5. We are optimistic about collaboration.

6. Our versions will start with this structure
   0.1.0 -> Bare Minimum, Minimum vial product (mvp)
   0.2.0 -> Introduce the tags we currently have
   0.3.0 -> Deprecate old # tags we don't wanna use (duplicates, technical not nessecary)
   1.0.0 -> Removal of deprecated tags and final list of currently used tags (2023)
   1.1.0 -> First new features we want to introduce, deprecated #mp3 and chaotic time units (2023)
   ~1.2.0 -> more new features (2024)
   2.0.0 -> Removal of #MP3 and introduce unified time units (=doing breaking changes) (2025)

---

details B 🎉:

1. The version names will be years like v1, v2023, v2024
2. The structure and meaning will be:
   v1 ->

• All the #tags that the games & tools have in common up till now

v2023 ->

• new features we want to have this year very much
• removing all the duplicate and unnessecary tags (like resolution, duetsinger etc.)
• deprecating mp3-Tag

v2024 ->

• next new cool features
• removing #mp3 (breaking changes)

details C ❤️ :

like A) but with v0.1.0, v0.2.0, v0.3.0, v2023.0.0, v2024.0.0.

---

(i) Besides the three options we agreed on:

• generally give developers ~one year for a format release to adapt, and then switch automatically to a new version
• quick releases outside annually turnus only if a major failure happens that disturbs continuity and acceptance completely.

(ii) Regardless of A/B/C we expect this following co-working beheaviour from all parties:

Roles / Behaviour	Who	To-Do
Creator Software	Karedi, YASS Reloaded, USDB-SYNCER, UltraSinger, UltraStar Manager	Aiming for the latest version, so new songs are automatically up to date
TXT-File-Hosting	USDB.animux Admins	Boost all online files to the latest released version
Games	UltraStar Deluxe, Melody Mania, Performous, Vocaluxe, My Little Karaoke, etc.	support latest version
Enduser	players, song creators, song manager	Updating/QA songs in usdb, Load new songs via USDB-SYNCER, stay in sync with usdb

(iii) We make this stragety transparent on our website usdx.eu/format
(iiii) As a temporairly overview we use this spreadsheet

[Baklap4]

Just a side note, semver doesn't exclude weekly, monthly or yearly releases. We can decide when we want to release a version. Semver says more about compatibility and what to expect from versions than a v2023 or v2024

A v2023, v2024 etc only says something about when something was released, but not if it's breaking, if new features have been added, if stuff got deprecated

I get it from an end-user (a singer of a karaoke game) perspective, but its not like the singers will look into the txt files anyway. It's the karaoke programs, creator software and websites which will look for this version. And they should get as much info there as in regard of versions and what to expect from that. There's a reason most libraries out there use semver
There's also a reason applications/oses use date-versioning: Endusers can expect when a new version drops

The target for the format project are developers, not end-users

[basisbit]

Two more cents from my side:
I personally love to use semver for everything, except when the version number is needed to have the users push stuff forward.
I think that this here is such a case. We have lots of users out there who only very rarely / occasionally interact with the ultrastar karaoke community (including the developers). the "ultrastar karaoke community" is very much split into many small parts who only occasionally interact with each other. An exception to this is the discord server which recently was started, however I personally guess that this will probably not "last" for more than a couple of years until people abandon Discord as the main place for such things. This has happened similarly a couple of times before.
Now, keep in mind we are such a loosely coupled community and many people who play the karaoke game only occasionally download a new game version and/or download new content to sing, for example once a year for a xmas party or a new years eve party. Whatever versioning scheme we decide on, we have to think of the effects this has for those different types of players.
Besides that, there is the additional workload which these format changes cause for the occasional contributors of the various karaoke game projects. Most of us only do this in their free time, and usually only with motivation for a few weeks/months, then take a break and maybe return again and again whenever we are motivated again. Often the motivation comes from us wanting to play karaoke ourselves.

All of this causes these requirements imho:

• reduce amounts of breaking changes
• make it easy to understand for other developers until when they "might have to" finish some certain changes in order for users to not have any issues with incompatibilities
• give plenty of time for occasional participating developers to implement it without it making the development effort stressful
• give plenty of time for occasional participating developers to get a say in format change decisions
• give plenty of time for new versions to be distributed to majority of users before they might encounter a file with a new "breaking" format change
• somehow get existing installs of the karaoke games to be updated "often enough"
• somehow reliably get the song collections which people have out there to be updated before deprecated features get abandoned (also keep in mind deprecated but not yet abandoned features probably get less testing / test coverage), but only start upgrading files and start using the new format after a certain date.
• if possible do not disturb users with "what file format you want to download" or "pick a format version to save as" questions because users probably don't know what to pick when for what reason and it also is bad UX to ask such stuff
• define how the applications should react if they encounter a song txt file which they don't yet support - differentiate between breaking change and non-breaking change
• get the users to understand when they need to push developers to add support for a new version/feature, so that karaoke games whos' develoeprs don't participate here still eventually implement the changes.

I don't think the solution to the above things is a strict semver vs yearly-release question. You can mix them both after all, if desired (for example v2016.1.3 and v2018.0.1 and v2023.0.2) and thus get the limit of one breaking change version release per year. Just pleas keep in mind that the minor and patch versions make it more difficult to synchronize and make it more overhead for developers.

[marwin89]

Updated the version strategy spreadsheet with a "year+ solution"

[achimmihca]

a #VERSION tag might be helpful to determine how the rest of the file should be parsed

It looks like the currently suggested approach is not doing this.
Instead, the projects are recommended to silently implement the latest version only?

---

EDIT: Don't know where I was looking. There is obviously a #VERSION in the spreadsheet. I didn't find it in the discussion and thought is was gone. Nevermind...

---

I think adding a #VERSION tag makes sense as it makes changes to the semantics explicit.

Note that projects (games, editors, etc.) could still decide to only implement the latest version.
For example, they could reject song files that do not have a #VERSION tag or that use an unsupported #VERSION.

But the advantage is that version changes could be communicated to the user, for example
- "txt file is missing #VERSION, see https://usdx.eu/format"
- "txt file version outdated, please update to vXYZ. For more info see https://usdx.eu/format"
- user asks "why is my song doing [something]" and developer can answer "if you want it to do [something-else], then specify version vXYZ"

Note that semver would be helpful to determine whether a project still supports a given version or whether it should reject it with a corresponding error message.

[marwin89]

SUMMARY / RESULT 🚩

Thanks for voting. Here is the final result for this issue.

We use clear semantic versioning SEMVER (developer perspective) to organize our versions.

1 🎉 / 6 🚀 / ❤ 0

short:

Clear Semantic Versioning SEMVER [v1.1.0]

• What: deprecating and add in minor versions, remove in major versions.
• Advantage: smooth transitioning, official international standard, understood by devs and tools (breaking changes)
• Disadvantage: not understandable for players

details:

1. Our versioning strategy for UltraStar Song Format specification is based on semantic versioning SEMVER.

2. We deprecate features in minor versions.

3. We remove features in major versions.

4. We add features in minor versions.

5. We are optimistic about collaboration.

6. Our versions will start with this structure
   0.1.0 -> Bare Minimum, Minimum vial product (mvp)
   0.2.0 -> Introduce the tags we currently have
   0.3.0 -> Deprecate old # tags we don't wanna use (duplicates, technical not nessecary)
   1.0.0 -> Removal of deprecated tags and final list of currently used tags (2023)
   1.1.0 -> First new features we want to introduce, deprecated #mp3 and chaotic time units (2023)
   ~1.2.0 -> more new features (2024)
   2.0.0 -> Removal of #MP3 and introduce unified time units (=doing breaking changes) (2025)

(i) Besides all we agreed on:

• generally give developers ~one year for a format release to adapt, and then switch automatically to a new version
• quick releases outside annually turnus only if a major failure happens that disturbs continuity and acceptance completely.

(ii) We expect this following co-working beheaviour from all parties:

Roles / Behaviour	Who	To-Do
Creator Software	Karedi, YASS Reloaded, USDB-SYNCER, UltraSinger, UltraStar Manager	Aiming for the latest version, so new songs are automatically up to date
TXT-File-Hosting	USDB.animux Admins	Boost all online files to the latest released version
Games	UltraStar Deluxe, Melody Mania, Performous, Vocaluxe, My Little Karaoke, etc.	support latest version
Enduser	players, song creators, song manager	Updating/QA songs in usdb, Load new songs via USDB-SYNCER, stay in sync with usdb

(iii) We make this stragety transparent on our website usdx.eu/format
(iiii) As a temporairly overview we use this spreadsheet

[codello]

I have just read this thread and have a question: Is the versioning scheme supposed to be semver compliant or just semver-inspired?

Semantic versioning has some aspects that make parsing and comparing versions more complicated than necessary (without an obvious benefit for a file format specification). For example 1.2.0-rc.2+foobar is a valid semver, which is less than 1.2.0. Implementing all the logic associated with semver parsing and ordering seems to be error-prone and complicated with basically no benefit (there is no such thing as a pre-release for a file format spec and neither is there build information).

Reading the thread above gave me the impression that the intent is to use a semver-inspired versioning scheme with the syntax 1*DIGIT period 1*DIGIT period 1*DIGIT (syntax as in #48). This would be understood to be a major-minor-patch triple with semantics similar to semver (major version change indicates a breaking change, forward-compatibility within a single major version).

Can someone clarify the intention of the current decision?

[Baklap4]

You're correct, semver inspired. We didn't see a usecase for release-candidates, pipelines, beta's, alphas etc.

So basicly 1.2.3 (major.minor.patch) as described in the comment above yours