Make formatVersion in metainfo.plist a major/minor

[typesupply]

We have switched to an incremental approach to updating the spec rather than holding lots of changes until a major version bump. To make it easier for readers to more easily identify these new format UFOs we need to make the formatVersion in metainfo.plist a float instead of an int.

[justvanrossum]

Suggest to only ever to increment by 0.1, and not go over 3.9. After that 4.0 is inevitable and then we should change the format specifier in metainfo.plist.

[anthrotype]

What about, instead of changing the type of the existing formatVersion element from int to float (which would break existing implementation), we add an additional int element <formatVersionMinor> which defines the minor version, and the existing <formatVersion> continues to define (implicitly) the major version?
This way existing clients will (with all probability) ignore the extra element (unless they are overly strict in their validation), while updated clients will be able to read the new formatVersionMinor element and act accordingly.

We could settle on a versioning policy whereby we only ever change the major version when: 1) we remove support for existing pieces of data; or 2) change their semantics in a breaking way. Whereas we would bump the minor version every time we add extra elements or attributes to existing elements or define new public. lib keys or add whole new files to the UFO package.

[anthrotype]

(maybe formatMinorVersion reads better in English than formatVersionMinor)

[anthrotype]

Alternatively, we would be forced to bump the formatVersion directly to 4.0, that is bump the major version because we changed the type of formatVersion element itself from int to float.

[typesupply]

I like the formatVersionMinor idea. We have a versionMinor field in fontinfo.plist so I'm fine with the awkward order.

[benkiel]

+1

[anthrotype]

OK, I'll work on fontTools.ufoLib support for parsing a new optional formatVersionMinor element in metainfo.plist.
But what about the GLIF format attribute? Do we want to add a new optional formatMinor attribute? Or do we re-purpose the existing format attribute to be a dot-separated "minor.major" string?
XML attributes (unlike plist) do not have an intrinsic type, they're just strings.
I am leaning towards simply doing format="2.1", instead of adding new formatMinor for GLIF.

WDYT?

[benkiel]

That sounds like the simplest thing

[anthrotype]

Hm. However the whole point of defining an additional minor version was to avoid breaking existing tools, since the new features are meant to be additive. If we change the meaning of GLIF format attribute from an integer to a dotted version string, then existing tool will break (e.g. you won't be able to read a UFO 3.1 with GLIF 2.1 in an editor that only supports up to UFO3/GLIF2).
Older versions of fontTools.ufoLib, to take one, will refuse to load such GLIF 2.1 with "Unsupported format version" because it casts to int() and check if it's in (1, 2).

[anthrotype]

cc @justvanrossum

[benkiel]

@anthrotype You've just argued against your earlier lean; but this raises a really good point. Based on that, I would think the thing to do is to also add formatMinor to GLIF, keeping format for the major format. Nothing will break then.

[justvanrossum]

Should we consider bumping the major version to 4 after all, but keep the amount of spec changes low, to increase the chance that it will be adopted soon?

[anthrotype]

I think adding a extra formatMinorVersion (and formatVersion attribute in GLIF) would give lend us more flexibility in the future for adding non-breaking-changes stuff like the verticalOrigin.
The way I'm implementing them in ufoLib is so that a UFO 3.1 will still be read in by older versions with its additional data (silently) ignored. I think this is better than the font being completely rejected as invalid, especially for things like the verticalOrigin or height which are relatively less common in predominantly horizontal-scripts-centric font develpment workflows.

[justvanrossum]

more flexibility in the future

Oh, that is beyond doubt.

If you think we can pull off a 3.1 without breakage that would be awesome.

(glyph.height returning None instead of 0 would be a breaking change, though, no? #95)

[anthrotype]

(glyph.height returning None instead of 0 would be a breaking change, though, no?)

hm, you got me there.. 🤔
The current behavior of glifLib is to not write a height attribute when the glyph.height value is 0.
Whereas the new glifLib would not write the height attribute when getattr(glyph, "height", None) is None.
So if one reads a new GLIF 2.1 using the old glifLib, then an omitted height attribute would be mistaken for a height of 0. That's not good, but..
Conversely if one reads an old GLIF 2.0 using the new glifLib updated to support formatMinor and new optional-height-default, then we could decide to do two things when faced with an omitted height attribute:

1. either we interpret this as an implicit height = 0 (but then as we save the UFO with the latest format all the glyphs will end up with an additional explicit height set to 0; maybe not too bad); or
2. intepreted as (incorrectly) meaning that the default height (asc - desc) is not overridden by this particular glyph and be unset to None.

Ah, another thing. Since these proposed changes to verticalOrigin and glyph height only concern the GLIF file and not the rest of the UFO files or structure, and given GLIF format has a version of its own, I think it would make more sense to only increment the GLIF format version (from 2 to 2.1) and not also the UFO format version which could stay 3 (err 3.0, formatVersion=3 and implicit formatVersionMinor=0 in the metainfo.plist).

[benkiel]

Regardless of the #95, I think we need to add the additional minor format versions to the spec, it's clearly needed.

[justvanrossum]

I'd be curious about @BlackFoundry's opinion about the height issue, given they use ufo for cjk.

[anthrotype]

I made the change in fonttools fonttools/fonttools#1786 but I am not sure where exactly we should mention these new formatVersionMinor (in metainfo.plist) and formatMinor attribute in GLIF <glyph> element. Technically they don't belong to the current UFO 3(.0) and GLIF 2(.0) specs, but to the not yet defined UFO 3.1 and GLIF 2.1.
Maybe I can merge that fonttools PR now (given it doesn't change reading/writing current UFO, as the minor digit is omitted/implied when 0), and then when we are ready to push some backward-compatible change to the spec, we'll mention in the new section for the newly defined spec version that it adds these new elements/attributes?

[benkiel]

☝️ This makes the most sense, and is a good prompt to get some spec updates for UFO 3.1 and GLIF 2.1 started and done. Otherwise, we can bump to 3.1 and 2.1 just for this, but that seems silly. @typesupply?

[typesupply]

Fine with me if everyone else is cool with it.

[typesupply]

Since this has been rolled out in ufoLib, should it be labelled a UFO 3 or UFO 4 issue? Also, can someone familiar with the change to ufoLib to support this write a description of what it does so that it can be documented?

[alerque]

Is it too late to revisit this? I don't think float makes any sense for version numbers and is just going to confuse the issue and make other things hard down the road. Floats just aren't good for versioning. Using a major/minor or even major/minor/patch versioning scheme would be awesome (ala Semver) but a float just confuses the issue. It won't be backwards compatible, it will look like a mathematical value but you won't be able to do normal math (x < y) on it, etc. Of course the other option is to just stick with integers. If introducing a breaking change from 3 to 3.1 is somehow okay (i.e. an existing field that needs parsing as a different type) then just calling it 4 and not being afraid to run up the integer count is probably a better plan.

[justvanrossum]

Check ufoLib: it has not been implemented as a float, but as major/minor.

[benkiel]

I'll write doc for this. Will do this weekend.

[benkiel]

And, this should be in 3.1.

[typesupply]

I've been working on documenting the specification process and "what version of the spec should this proposal apply to?" is near the top of the page. We have two models for that now:

1. A change that would trigger code changes in existing tools goes to the next major version.
2. A change that can be implemented via a lib key goes to the current version.

Where would the minor version fit into this? Is it a hint to tools that "this UFO was last touched by a tool that knows about X, Y, Z new things"? I'm just trying to figure out how to fit this into the process.

[benkiel]

I think that @anthrotype will have a better nuanced view than I, but i would say that minor versions are for things that won't break existing tools but add information, such as the addition of version minor (yes, this is recursive). Additions to fontinfo would fall under this too, at least in my mind.

[typesupply]

i would say that minor versions are for things that won't break existing tools but add information, such as the addition of version minor (yes, this is recursive).

Makes sense. I'll work this into the process.

Additions to fontinfo would fall under this too, at least in my mind.

Cool. That relates to #128.