Add version to MNX documents

[mscuthbert]

Already realizing that we will need a "version" attribute in the root element. My preferred ways are either to use an object with mixed ints and strs/enums:

{
  "version": {
    "major": 0,
    "minor": 1,
    "patch": 0,
    "status": "alpha"
  }
} 

or two attributes, one an array of ints, the other a str/enum:

{
  "version": [0, 1, 0],
  "version_status": "alpha"
}

acceptable also is [0, 1, 0, "a"] style, but I think this makes comparisons harder. But definitely not a string that has to be parsed like "version": "0.1.0a2"

Reserving odd minor numbers for releases and even for beta (or vice-versa) is also generally a good plan.

If you don't care that all your major releases are numbered 1.1, 2.1, etc. and not 1.0, 2.0, etc. then it's pretty easy to filter by major releases and beta status. (This is what music21 adopted)

[mnquintana]

Does MNX need the granularity of minor and patch version numbers? What would they be intended to communicate?

Assuming the versioning would conform to SemVer, bumping the minor or patch versions would indicate non-breaking changes to the spec. But is it logically possible to make a non-breaking change to a standard like MNX? If it is, what would be some good examples? And do we really need both a minor and patch version?

[mscuthbert]

yeah, I was thinking maybe patch versions weren't necessary, but I also thought that there are version comparison tools in most modern languages that count on them. I do think that two levels are needed -- perhaps making the second level be the SemVer level. The distinction between big changes and small changes is usually helpful

[samuelbradshaw]

I agree that both major and minor versions are needed, and that a patch version isn't as important, but I'm not opposed to having a patch version if it would help with compatibility.

[adrianholovaty]

I'm also struggling to see the benefit of such granularity. MusicXML has used just two numbers (3.1, etc.); has there been any issue with this historically? I can't think of any practical issues and this smells like overengineering.

My vote would be either of these:

{"version": "1.1"}

{"version": [1, 1]}

[webern]

an array of ints

Please no. Prefer objects for things that have positional fields. Arrays for dynamic-length lists of the same "thing".

IMO there is nothing wrong with "version": "1.1.2". I know we are moving away from microsyntaxes, but semver strings are very common. The object format considered above is also fine.

Semver in MNX could be defined as

Major: breaking changes, e.g. a field is removed or renamed breaking backward compatibility
Minor: additive changes, e.g. a field is added or an object type is added without breaking backward-compatibility
Patch: edits to the spec that have no affect on parsers or generators (e.g. documentation edits, formatting edits)

[adrianholovaty]

After discussing with my fellow co-chairs in our biweekly chat, I've just pushed commit a09d15e. This documents a new top-level "mnx" key, which contains a "version" key — a single number. We'll increment this number when making changes to the spec.

All example documents now have this data, so you can see it in action.