File Format Version

I just caught myself in an error, and I made the mistake because I can't ever really remember there being any guidance on what to do about the file format version number. I had to go do a bit of digging to figure this out. It seems past time to establish some formal policy on this one, so the mistakes of the past can be avoided in the future.

Rosegarden uses the file format version numbers to decide when to warn the user about incompatibilities between files saved with different versions. These should be updated when the file format changes, which usually means whenever we add new features. This code can be found in src/document/RosegardenDocument.cpp

int RosegardenDocument::FILE_FORMAT_VERSION_MAJOR = 1;
int RosegardenDocument::FILE_FORMAT_VERSION_MINOR = 5;
int RosegardenDocument::FILE_FORMAT_VERSION_POINT = 0;

Increment the major version number only for updates so substantial that we shouldn't bother even trying to read a file saved with a newer major version number than our own.

In practice, this hasn't happened in 10 years, and is unlikely to happen in the future. Leave the major version number at 1 unless you know damn sure what you're doing.

Increment the minor version number for updates that may break compatibility such that we should warn when reading a file that was saved with a newer minor version than our own.

In practice, this should be done any time we make changes that add new XML element types, or extend existing ones. What prompted the creation of these guidelines was that I added several new types of events to what is now file format version 1.5.0, and I wanted to investigate what would happen if I created a file that contained some of these events, and loaded it with the previous version of Rosegarden. Of course it silently stripped out all the new events with no protest, because I hadn't changed the minor version number (until just now).

Looking back, I can think of a great many times when we should have changed the minor version number, but did not. It should be much higher than it is now, but there is no advantage to jumping it up to account for all the missing increments. We need to pay more attention to this in the future! It's not life or death stuff here, because we seem generally able to preserve elements from the future without stripping them out (to my pleasant surprise it turned out just now) but this just seems like good housekeeping.

We should not hesitate to change this whenever we introduce any change to the XML file format. (Hopefully if you do this, you know what you're doing when you do it, and I don't have to spell all of this out for you.) We should increment the minor version number on the first XML change in a given release cycle, and leave it there until the release is away. There is usually no need to increment this multiple times in the same release cycle.

Not used for any comparison calculation, so it's pretty irrelevant. Leave it at 0, and ignore it.