cue-lang
cuelang.org/doc/concepts/logic: clarify backwards compatibility for APIs
Discussed in https://github.com/cue-lang/cue/discussions/1539
Originally posted by andrewzhurov February 21, 2022
With optional fields it gets a bit more subtle, but basically, an instance may change an optional field to required, but not remove it. The backwards compatibility metaphor applies here as well. source
From the explanation of that section I understood that in API methaphor we speak of input of API and it is told that a more specific version is backwards-compatible.
From my understanding, there are two sides to backwards-compatibility - of input and of output.
Whereas a backwards-compatible change for input is easing of requirements. I.e., a new version of API takes less to produce the same result. E.g., v1 takes wood+stone, v2 takes wood. E.g., v1 takes high-quality wood + stone, v2 takes wood+stone. I.e., it is fine to ease from required -> optional -> absent. As well as ease specificity of stuff.
A backward-compatible change for output is giving more and/or more specific. I.e., a new version of API gives more stuff and/or more specific stuff for the same input. E.g., v1 gives an axe, v2 gives an axe and a hammer or v2 gives a high-quality axe.
From that understanding it follows that a more specific version of input of API is not backwards-compatible. Could you point whether I'm mistaken somewhere?
You are correct, the text is just very unclear. The clear part is here.
..., the old version must be an instance of the new one [for backwards compatibility to hold].
In other words, newer APIs indeed should become less specific, as you point out.
So "the instance" referred to in your quoted text refers to the old version, I think. If not it is a bug. It is highly confusing and arguably not correct as changing implies a newer version.
Also,
For a newer version of an API to be backwards compatible with the previous version it must subsume it.
It is unclear which it refers to which version.
Anyway. You are correct and the text is unclear if not wrong. With closedness in the mix as well, things get a little more subtle, btw.