[Spec] Define Versions: 0.1.0 till 1.1.0

[marwin89]

Suggestion

According to #13 strategy:

1. We need to define a version for undefined song txt-files first.
2. This version represents all text files that we currently host on usdb.animux (as of today 2023 Sep 26th) and other txt-file-hostings.
3. This version defines the bare minimum that every song needs to played and hosted.
4. Do you have a draft already? Please post in this issue and lets discuss.

Use case

Start versioning. Having a version we can build up upon and categorize txt-file entries in hostings.

Extra info/examples/attachments

• Don't know if "v.0.1.0" is appriopiate. please discuss
• We definitely need a version tag #VERSION at the start of a txt-file mentioned in [Spec] Come up with a versioning strategy #13.

[marwin89]

To get things started. What about this? Please add or correct 🙏

#VERSION: 0.1.0
#TITLE: Title of the song
#ARTIST: Name of the Artist
#MP3: Filename auf the audio file.mp3
#COVER: Covername.jpg
#BACKGROUND: Background.jpg
#VIDEO: Video.mp4
#GAP:12.4
+Normal Notes
+Golden Notes
+Freestyle Notes
+Rap Notes
+Golden Rap Notes
E

Out of scope for this version: duet, medley, vocals, instrumental, etc.?

[Baklap4]

I'd define version 0.1.0, but also treat every file without a #VERSION tag to be 0.1.0. This should be mentioned somewhere
Maybe @bohning can include the new tag upon downloading through USDB_Syncer, maybe that AnimuxAlex can include it for every txt file on the server

As for bare minimum i'd only include the header tags:

• Artist
• Title
• MP3
• BPM

Things like covers and backgrounds are all optional

for the notetypes i'd say:

• Normal notes
• E

Because the others are also both optional

Then from this version on. We'll have 2 more versions within the 0.x series:
0.2.0 -> Introduce the tags we currently have
0.3.0 -> Deprecate tag tags we don't wanna use
1.0.0 -> Removal of deprecated tags and final list of currently used tags
1.1.0 -> First new features we want to introduce
etc....

[marwin89]

Here is a new spreadsheet table page for us to organize the versions. edit as you like:

Versions Overview spreadsheet

[marwin89]

Updated format version spreadsheet: 📝

🔗 Versions Overview Spreadsheet

Please mind: release date of format versions and implementation date are different things. You decide when the new versions are implemented in your software

[Nianna]

The spreadsheet is a nice idea but it would be nice if it contained all information and was a single point of truth. Now by looking just at it I feel like I'm missing half of the info that is probably spread over various issues here on github.

Could you please add info why the tags were deemed deprecated and why others were renamed?
For example I don't see why we would want to rename #MEDLEYENDBEAT to #MEDLEYEND? Is there any gain in that?

Also, what are the new tags supposed to mean? e.g. #ONLINE ?

[Nianna]

I'd define version 0.1.0, but also treat every file without a #VERSION tag to be 0.1.0. This should be mentioned somewhere Maybe @bohning can include the new tag upon downloading through USDB_Syncer, maybe that AnimuxAlex can include it for every txt file on the server

But why? Can't we treat version 0.2.0 (using excel numeration) as default version?
None of the songs right now have #VERSION tag. But many of them do have tags like #GAP, #VIDEO, #COVER. Treating the files as files in version 0.1.0 would mean that these tags are supposed to be ignored cause they are not a part of version 0.1.0.

[Nianna]

I would suggest:

1. treating the list of all tags that we collected just as a reference list - this is not a version. Let's not make this mess sth "standarized"
2. Defining version 1.0.0 - first offixial version - which should be the "cleaned up" version that is logically sound - contain no duplicated tags (e.g. leave only P1, remove #DUETSINGERP1; remove all deprecated tags, #MP3 tag may be renamed to #AUDIO, we may require support for multi-values in some tags (e.g. creator) and for different units in time related tags. The last to are up to discussion.
   This version should not have new features, just minimal changes to clean up what we have now into something that makes sense.
3. Finally - start working on version 1.1.0 which will have all new shiny features like #INSTRUMENTAL, #VOCALS, #ONLINE etc.
   We should give plenty of time for everyone to implement version 1.0.0 before releasing 1.1.0
   All new version starting from 1.0.0 should be backwards compatible (unless there is a really really good reason to drop backwards compatibility, but in such case we should use new major version e.g. 2.0.0)
4. Create some standalone tool that will automatically convert all user's songs from no format to format 1.0.0 and between format versions.
   The advantage is that the first official standarized version will already make logical sense. And later we can slowly build upon that

[Baklap4]

Overall: a lot has been discussed in other issues. It might be hard to follow all of the activity, but i tried my best to summarize it here based on your statements/questions @Nianna

The spreadsheet is a nice idea but it would be nice if it contained all information and was a single point of truth. Now by looking just at it I feel like I'm missing half of the info that is probably spread over various issues here on github.

The spreadsheet will be long gone after things have finalized. The single point of truth will be this repository

Could you please add info why the tags were deemed deprecated and why others were renamed?
For example I don't see why we would want to rename #MEDLEYENDBEAT to #MEDLEYEND? Is there any gain in that?

This has to do with an open issue #24 as noted the namechange will only happen after 1.0.0 in which these tags can get deprecated. Also everything currently in 1.1.0 or higher is only theoretical so please join these active tickets. It's not set in stone yet

Also, what are the new tags supposed to mean? e.g. #ONLINE ?

Also an open item as of yet #22

But why? Can't we treat version 0.2.0 (using excel numeration) as default version?
None of the songs right now have #VERSION tag. But many of them do have tags like #GAP, #VIDEO, #COVER. Treating the files as files in version 0.1.0 would mean that these tags are supposed to be ignored cause they are not a part of version 0.1.0.

Purely to define the basics you need to get started. Yes i agree that many texts out there already contain a lot more, but if you'd just want to have a song to be singable in all of the apps these need to be defined. However we can automate things when certain tags are available to make it up to atleast 0.2.0 (as most songs probably would qualify). This will be a seperate process and is out of scope for this discussion.

treating the list of all tags that we collected just as a reference list - this is not a version. Let's not make this mess sth "standarized"

I agree that the collected list is a reference list. For the 1.0.0 we already scrapped some tags like #RELATIVE (all colored red within 0.3.0) If you think this list might need a more thorough cleaning please join the discussion that's why we're all here ;)

Defining version 1.0.0 - first offixial version - which should be the "cleaned up" version that is logically sound - contain no duplicated tags (e.g. leave only P1, remove #DUETSINGERP1; remove all deprecated tags, #MP3 tag may be renamed to #AUDIO, we may require support for multi-values in some tags (e.g. creator) and for different units in time related tags. The last to are up to discussion.
This version should not have new features, just minimal changes to clean up what we have now into something that makes sense.

#AUDIO is a newly introduced tag which came from the discussions in discord / issues here. Personally i'd file this under 1.x.y since its new and not yet defined whereas #MP3 is fully defined.
Gonna link my previous comment on how i got to the versioning -> #13 (comment)

Finally - start working on version 1.1.0 which will have all new shiny features like #INSTRUMENTAL, #VOCALS, #ONLINE etc.

Every version after 1.0.0 can contain anything new and shiny. Agreed. This is already reflected within the spreadsheet.

We should give plenty of time for everyone to implement version 1.0.0 before releasing 1.1.0

I disagree. Sure the software should catch up eventually. But we won't be able to control what everyone on the web is doing. So there's no need for us stopping to invent stuff and come up with things.

All new version starting from 1.0.0 should be backwards compatible (unless there is a really really good reason to drop backwards compatibility, but in such case we should use new major version e.g. 2.0.0)

Since we're using semver this is already the case. Please read up on the linked comment of mine :) #13 (comment)

Create some standalone tool that will automatically convert all user's songs from no format to format 1.0.0 and between format versions.

Tools like usdb-syncer or creator software should always try to aim for the last version. This will make sure that eventually all the songs get pushed towards the latest. Like also already mentioned we could create statistics about version usage and eventually try to bump everything to the latest. But this will be a huge operation. IMHO we or an automation tool shouldn't alter users local songs. That's the job of the song-providers (usdb.animux.de / ultrastar-es / others) and creator software.

Karaoke programs will have to probably implement all the versions to be of best service. However if they want they can start from 1.0.0 and hopefully soonish we'll have everything ported to 1.0.0

[rakuri255]

Do we need E end of file? I mean it is clear to every software when end of file is. You don't need to define that extra.

[marwin89]

I've updated the spreadsheet

Version overview spreadsheet

[Baklap4]

Do we need E end of file? I mean it is clear to every software when end of file is. You don't need to define that extra.

I'm not quite sure why E was a thing to begin with. Maybe someone can explain how it got into place?
As @rakuri255 mentioned for developers end-of-file is easy enough to detect. Maybe a usecase for non-developers we might miss?

[Nianna]

The spreadsheet will be long gone after things have finalized. The single point of truth will be this repository

I just meant to use it as a single point of truth while we work on the draft, with tags being linked to the related issues for reference. Just like @marwin89 did, thanks for that 👍

That's the job of the song-providers (usdb.animux.de / ultrastar-es / others) and creator software.

It's just not gonna happen. Also it will not update the songs that users have locally. Without any tool that we can tell the user to use, all formats will have to be supported like forever. But I never meant it to be a part of this project, so it's unrelated to this issue.

I still do not see the point of having v0.1.0. Same with v0.3.0 - new version just to deprecate some tags?
Why can't we have just one version instead of these 3?
We could define a list of required tags, a list of optional tags + info which tags are deprecated (and what should be used instead if applicable).

As you have said yourself- all tools will have to implement all versions. Why make the life harder for everyone and define 3 versions instead of 1?

[marwin89]

FYI: OVERVIEW Spreadsheet updated (semver strategy vs anual strategy)

[marwin89]

Pre-Condition for this issue:
we need to agree on version strategy #13 first to continue this issue. There is a voting till 14th oct 2023.

[achimmihca]

With 0.2.0 we (format project) want to specify tags that are already out there.

I think this is beneficial for communication with users.
You can just point them to the spec and from there they can find how the format changed and thus how to update their songs.

[marwin89]

Summary / Final Results 🚩

Thanks for discussing version structure. We voted for this in issue:

• [Spec] Come up with a versioning strategy #13

Here are the final results.

Result:

• We structure Versions starting from minimum. This ensures traceability.
• First real version is 1.0.0.
• We have a complete version table from 0.1.0 to 2.0.0 (2023-2025).
• Version table will be uploaded to usdx.eu/format website

Version Table:

Details:

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)