[Process] Introduce compatibility-based Versioning?

[marwin89]

edited on 6th Feb 2025

About this issue / Summary

1. Marwin wanted to release URL-Header [Spec] Add #AUDIOURL, #VIDEOURL, #COVERURL, #BACKGROUNDURL #22 according to roadmap.
2. This would result in a new minor version 1.2.0
3. a discussion came up not to do a feature-based versioning but rather a compatiblity-based versioning.
4. We agreed on doing a compatiblity-based versioning.
5. in a pull request Codello splits spec.md by versions and applies compatibility-versioning.
6. We will re-structure how a version 1.2.0 should look like
7. URL-Header can be used (pre-release)

[codello]

Can we clarify the intent behind versioning the file format? Versioning for a file format works differently to versioning an application. It is easy to update an application to get new features but it can be hard to update a file format to a new version. IMO a new version of the format should be carefully considered.

I would personally expect that a file format change marks an expected change in behavior (that might be backwards-compatible). I don't think the current change set (basically #22) qualifies for that. We can just add these headers to version 1.2.0 without breaking anything. The headers are optional anyways.

In other words: Take an example application that implements the AUDIOURL header. Now take the following song file:

#VERSION: 1.1.0
#AUDIOURL: https://youtube.com/...
…

The AUDIOURL header is not defined in version 1.1.0. Should it be ignored? I personally think it is more clear to amend versions with backwards-compatible changes as long as possible and try to introduce as few versions as possible to avoid an overly complicated compatibility matrix of features/headers and versions.

[Baklap4]

Currently versioning in semver has been agreed upon as per #13
We achieve transparancy in what is being changed in which version. Each change is carefully considered so we dont break compatibility.. as of yet we didnt have to update the major version.

This also allows us to deprecate things we want to phase out.

In the end a karaoke program can opt in to support a specific version. Each txt annotated with that should be compatible. Currently the usdb syncer supports up to 1.2.0.
Same for Ultrasinger. Ideally we would add this to hosting parties (usdb) itself too.. so people can download the correct version for the software theyre using, but that means bigger changes there.

As for headers not specified in the format, they should not break the game experience. Therefore we would suggest to ignore them, rendering them useless. If a new header is needed the format team will have a discussion about it to unify its existence

[codello]

Ok, I understand. While I disagree with some of the decisions in #13 I can accept that the decision is final.

My concern is mostly that a larger number of versions can lead to confusion which header is available in which version. Even if the specification is clear about this, I see a risk that an implementation respects all headers it supports, regardless of the version specified by the file. For example I could imagine that an implementation would respect the AUDIOURL in a song with version 1.1.0. This is not inherently problematic but if enough implementations do this then the version number becomes meaningless. I'm especially worried that at some point song creators will use wrong version numbers "because it works anyways" (I don't expect song creators to be familiar with the formal specification).

But maybe I'm overcomplicating things here and all that is not really a problem…

[Baklap4]

Tooling for creating songs should aim to support the latest version available. Therefore newer txt files will eventually be only made and distributed within the latest format. I don't expect song creators to know about the specification, however the tooling they're using should guide them into using the latest format i'd suppose.

Within usdb_syncer there's now an option to select a specific version cause not every karaoke software has implemented every version yet. This way you can set it once depending on the software you're using.

Personally i think if a version is specified, the program should aim to just support whatever is specified in said version. The software can however support more than what's specified. This is a nicety, but shouldn't be mandatory. This leads to software implementing at least a specific version where a standard has been defined. A new karaoke software can then more easily be released since it can opt to just support 0.3.0 at the first version, but support more in the end. This makes for faster development cycles.

I see a risk that an implementation respects all headers it supports, regardless of the version specified by the file. For example I could imagine that an implementation would respect the AUDIOURL in a song with version 1.1.0.

This is like you said not inherently a problem, the #VERSION header is mainly there to guide the developers on what to support in their software. Song creator tooling should aim to only release txt files with latest version (for now a selection since karaoke software is currently lacking support) -> https://www.open-music-games.org/play-and-create/games
As the format project i'd love to see a table within the readme specifying which project currently supports which version. And as mentioned in #32 release badges for programs to state that they do support said version

In the end i think it's good we defined versions, this way it's clear what each version contains and supports -> see the spreadsheet -> https://docs.google.com/spreadsheets/d/13fj_wtRHbSjaOaS1ehmCogoeFV9MyqY1eeiqkrJfhDA/edit?usp=sharing -> This might need to be better documented within the website/spec

This will also allow the developers to come up with new headers/functionality if they need to be there (as a result see 1.0.0, 1.1.0 and 1.2.0). Which are defined in unity rather than on a per project basis.
The end-user (singers) will get the best experience when they'll get the latest version of txt files out there. Albeit that the singing software is not up-to-date for versioning yet

[Baklap4]

Specfile has been merged already; website still needs an update, @marwin89 can you fix this?

[codello]

Thank you for the explanation @Baklap4. I can understand that perspective. I still think I am in disagreement though.

Personally i think if a version is specified, the program should aim to just support whatever is specified in said version. The software can however support more than what's specified. […] This leads to software implementing at least a specific version where a standard has been defined.

To me it feels like we are using the version to indicate a specific set of features of the format. #32 kind of reinforces this impression. However, I think that the main purpose of a versioned file format is to ensure compatibility. To me a new version of a file format indicates a change in compatibility (potentially non-breaking but a change nontheless). I wouldn't necessarily consider the introduction of new metadata a change in compatibility (compared to - for example - the introduction of a new note type).

In the end i think it's good we defined versions, this way it's clear what each version contains and supports

Definitely agree. I'm all for versioning. I do think, however, that it would benefit compatibility and adoption if we keep the number of different versions low and not try to release new versions quickly or regularly. This doesn't mean that new headers shouldn't be standardized, I just don't see the benefit increasing the version number for that.

As the format project i'd love to see a table within the readme specifying which project currently supports which version.

+1

[marwin89]

Specfile has been merged already; website still needs an update, @marwin89 can you fix this?

Hi @Baklap4 , I'll try to do it in 1-2 weeks 👍🏻 I got a lot to do in my job.

[Baklap4]

Definitely agree. I'm all for versioning. I do think, however, that it would benefit compatibility and adoption if we keep the number of different versions low and not try to release new versions quickly or regularly. This doesn't mean that new headers shouldn't be standardized, I just don't see the benefit increasing the version number for that.

I do agree with this. New metadata fields doesn't necessairly mean a new versionnumber. Preferably i think these should be collected while we wait for new functionality. They can then be added within that new functionality (for example a new note-type).

At some point we've collected enough to throw out a new version, this can either be compatible, or breaking. I'd still opt for every program to support up to the latest version if they want all the functionality. The programs can however decide to not support a version.. therefore leaving out that functionality

tl;dr

Not every addition or change of fields will result in a version bump. They'll be collected up untill we're ready to release a new version. As for the current 1.2.0
We designed to add in the ...URL fields. These are all optional and nothing else is added.. Personally i'd wait for a release of the 1.2.0. People can however use it (like usdb_syncer already does), this is however experimental / pre-release and not persé final since a release has not yet been finalized. As more 'features' are added onto 1.2.0 we can at some point say 1.2.0 includes: This, that and that other thing. Instead of just that one thing.

[codello]

If I understand you correctly this still sounds like versions being used for features instead of compatibility. It sounds to me as if new headers would only become "official" when they get "released" in a version. I think this approach makes it unnecessarily difficult to introduce new features.

The programs can however decide to not support a version.. therefore leaving out that functionality

Support for a specific file format should not be confused with support for a specific set of features. I think those are two entirely different things. And this is already the case: according to the spreadsheet the #COMMENT header is not supported by quite a lot of programs, yet the header was supposedly introduced in version 0.2.0 of the file format. Does this mean that all these programs do not support version 0.2.0 of the file format? I don't think that is a plausible classification.

Instead I think the version of the file format relates only to syntactic and semantic compatibility, i.e. if a program is able to understand the contents of the file correctly. Whether it supports all of the features being used is a different question that is outside the scope of a file format specification.

---

I would prefer the following approach. We differentiate changes according to 3 categories:

Does not impact compatibility

This type of change adds functionality without impacting existing implementations.

Example: Adding a new metadata header (let's say #COMPOSER). A song that uses this header can be opened in a game that does not support the header without experiencing any degradation. The song works as intended and the header can be safely ignored.

Impacts Compatibility

This type of change adds functionality that can lead to a degraded experience in older implementations that do not have support for it.

Example: Adding a new note type (let's say a vibrato note). A song that uses this note type can be opened in a game that does not support it and can be sung, but the vibrato notes will not work. They will be either missing or will be replaced by Freestyle notes. The song can still be sung and you can have a great experience, but you will experience some restrictions when newer features are used.

Breaking Change

This type of change adds functionality that is not backwards compatible.

Example: Changing the syntax or semantics of a required header (let's say we remove the implicit quadrupling of the #BPM header). A song that uses the new syntax/semantics cannot be used in a game that does not have support for it. The song would be completely broken on the old game (in this example because everything would be 4 times as fast).

These changes correspond to the following procedures:

1. Non-impacting changes get introduced retroactively to all versions of the file format that they are compatible with. In the above example the #COMPOSER header would be introduced to all versions of the file format. Implementations can choose to support the new header or choose not to. This has no impact on which file format versions they are able to handle.
2. Impacting changes require a minor version bump to be used. This wouldn't technically be necessary but I think this makes for a good user experience. Implementations that support the file format version 1.1.0 can emit a warning if they encounter a file using version 1.2.0 that the file might use features that are not supported by the program.
3. Breaking changes require a major version bump. Implementations are expected to refuse to open files that use a different major version than what they are compatible with. I think this is the part where we already agree.

New functionality is being standardized by means of issues and pull requests in this repo. When a pull request is created it must target ALL versions that are impacted (currently everything is in one file but as discussed in #32 this is about to change). As soon as the PR is merged the standardization process is complete and the feature is considered part of the specification. There is no further "release" process.

Note

For breaking changes I would agree that a "release" process is necessary and that we want to aggregate as many breaking changes as possible for a release.

---

If this goes against what was decided in #13 I can also accept a different approach and don't intend to challenge previous decisions. However, I do have a strong opinion that versioning based on compatibility instead of features would benefit this project immensely.

[codello]

I'd like to get some clarification/consensus how we want to handle this. I think this is a really important decision what exactly a version of the file format means that affects not only the processes in this repo but also affects how people are expected to interpret the specification.

I do think that compatibility-based versioning is the right way for this project. As we want to separate the spec.md file by versions anyway, I could create a PR that separates these versions and at the same time applies the compatibility-based versioning. Then we have a more specific example how this would look like and can maybe better discuss how to move forward. Would this be helpful?

[marwin89]

Hi @codello, hi @Baklap4 , sorry for not replying. I got so much work to do in my job right now. What a insightful discussion!

Summary

Codello,

• I definitely agree with you that compatibility is probably the right way to organize versioning of the song format.
• I happily wait with the release of v1.2.0.
• It would be very cool if you split the spec.md by versions and do a PR that applies compatibliy-based versioning to spec.md

Next Steps

• @codello [Processes] Split Spec.md by versions #76
• @codello [Proccesses] Apply compatibility-versioning on splitted spec.md #77