Closed doktorbro closed 10 years ago
This came up very briefly at our last meeting. We broke the SemVer semantics by dropping support for the /info.xml
syntax between 1.0 and 1.1 (probably in other ways as well). We're doing it again between 1.1 and the next revision as IIIF has settled on a namespace and any dependency on the compliance level or @context
URIs will break backwards compatibility.
I am interested in this idea and exploring it more. There would be a question of how to migrate to this method of naming from our current method. Three proposals for the image API:
@azaroth42, @zimeon, @snydman: thoughts?
Really, we're 1.2 with the pixels API and (IMO) 2.1 with the subsidiary information requests.
I understand the dependency management requirement, but the additions to me don't seem like a new major version. I don't see any backwards incompatibility in the Voodoo spec though. It seems like it would be 2.1 rather than 3.0. The URIs are always going to change, which would make the semver pointless if that triggers a major version update.
Basically ... I think we stick to our current scheme as the changes in the .json files are really minor changes -- they're extra information not the main part of the API, which is the pixels.
On Mon, Mar 10, 2014 at 6:59 AM, Jon Stroop notifications@github.comwrote:
This came up very briefly at our last meeting. We broke the SemVer semantics by dropping support for the /info.xml syntax between 1.0 and 1.1 (probably in other ways as well). We're doing it again between 1.1 and the next revision as IIIF has settled on a namespace and any dependency on the compliance level or @context URIs will break backwards compatibility.
I am interested in this idea and exploring it more. There would be a question of how to migrate to this method of naming from our current method. Three proposals for the image API:
1.
Alias approach:
Version 1 is SemVer 1.0.0. URIs only need to contain a '1', not 1.x.x as this would break back compatibility, so I think we're OK there.
- Version 1.1 is SemVer 2.0.0. Add 3xx aliases from URIs that contain '1.1' to URIs that replace it with a '2', or just make both URIs work.
- Next version is 3.0.0, future work on auth isn't likely to break anything, so after that it's 3.1.0
- Typo or HTML fixes, or clarification would increment the PATCH place. 2.
Keep public name separate approach:
Keep incrementing as we are now, but publish a SemVer number as well, somewhere near the top of the spec. The SemVer number should still be the number we use in URIs, as explained above. 3.
Just start, i.e. next revision is 2.0.0. I don't like this, but it is an option.
@azaroth42 https://github.com/azaroth42, @zimeonhttps://github.com/zimeon, @snydman https://github.com/snydman: thoughts?
Reply to this email directly or view it on GitHubhttps://github.com/IIIF/specifications/issues/47#issuecomment-37184436 .
Actually, we're 1.0.2 with the pixels as the changes are just documentation fixes.
R
On Mon, Mar 10, 2014 at 8:20 AM, Robert Sanderson azaroth42@gmail.comwrote:
Really, we're 1.2 with the pixels API and (IMO) 2.1 with the subsidiary information requests.
I understand the dependency management requirement, but the additions to me don't seem like a new major version. I don't see any backwards incompatibility in the Voodoo spec though. It seems like it would be 2.1 rather than 3.0. The URIs are always going to change, which would make the semver pointless if that triggers a major version update.
Basically ... I think we stick to our current scheme as the changes in the .json files are really minor changes -- they're extra information not the main part of the API, which is the pixels.
On Mon, Mar 10, 2014 at 6:59 AM, Jon Stroop notifications@github.comwrote:
This came up very briefly at our last meeting. We broke the SemVer semantics by dropping support for the /info.xml syntax between 1.0 and 1.1 (probably in other ways as well). We're doing it again between 1.1 and the next revision as IIIF has settled on a namespace and any dependency on the compliance level or @context URIs will break backwards compatibility.
I am interested in this idea and exploring it more. There would be a question of how to migrate to this method of naming from our current method. Three proposals for the image API:
1.
Alias approach:
Version 1 is SemVer 1.0.0. URIs only need to contain a '1', not 1.x.x as this would break back compatibility, so I think we're OK there.
- Version 1.1 is SemVer 2.0.0. Add 3xx aliases from URIs that contain '1.1' to URIs that replace it with a '2', or just make both URIs work.
- Next version is 3.0.0, future work on auth isn't likely to break anything, so after that it's 3.1.0
- Typo or HTML fixes, or clarification would increment the PATCH place. 2.
Keep public name separate approach:
Keep incrementing as we are now, but publish a SemVer number as well, somewhere near the top of the spec. The SemVer number should still be the number we use in URIs, as explained above. 3.
Just start, i.e. next revision is 2.0.0. I don't like this, but it is an option.
@azaroth42 https://github.com/azaroth42, @zimeonhttps://github.com/zimeon, @snydman https://github.com/snydman: thoughts?
Reply to this email directly or view it on GitHubhttps://github.com/IIIF/specifications/issues/47#issuecomment-37184436 .
Sorry, what were the "pixels API" changes? Is this something that predates my involvement?
Right now if I see @context: "http://library.stanford.edu/iiif/image-api/1.1/context.json"
, I'm going to a set of assumptions about what that server can do. The version is baked into that URI which means if I didn't get that URI from a IIIF server, compatibility is broken.
Going forward, we've added the protocol
key as an unchanging URI that servers can use as a hook, and then further examine the capabilities of the server based on response from dereferencing the capabilities
URI. With that in place, I agree that the URIs changing does not matter (as long as you're following your nose, and not simply making assumptions based on the URI as a key).
So, going forward, I agree with you, but IMO we're at 3.0.0-alpha right now.
On Mon, Mar 10, 2014 at 9:21 AM, Jon Stroop notifications@github.comwrote:
Sorry, what were the "pixels API" changes? Is this something that predates my involvement?
Nothing over the wire, just documentation tweaks. For example the clarifications about canonical URIs in the latest version, removing the broken Auth paragraph, clarifying floating point percents and rotations, etc.
Right now if I see @context: " http://library.stanford.edu/iiif/image-api/1.1/context.json", I'm going to a set of assumptions about what that server can do. The version is baked into that URI which means if I didn't get that URI from a IIIF server, compatibility is broken.
Yes, and we are always going to make a new context document for a new version, making everything backwards incompatible, making everything a new major version ... thereby defeating the point of any notion of semantic versioning.
Going forward, we've added the protocol key as an unchanging URI that servers can use as a hook, and then further examine the capabilities of the server based on response from dereferencing the capabilities URI. With that in place, I agree that the URIs changing does not matter (as long as you're following your nose, and not simply making assumptions based on the URI as a key).
It is certainly going to be better from now on, regardless of the exact label we give to it. But @context and profile URIs will change every time, thus it's technically backwards incompatible. As will any JSON-LD, or likely any serialization of linked data, based API.
R
On 03/10/2014 12:28 PM, azaroth42 wrote:
On Mon, Mar 10, 2014 at 9:21 AM, Jon Stroop notifications@github.comwrote:
Sorry, what were the "pixels API" changes? Is this something that predates my involvement?
Nothing over the wire, just documentation tweaks. For example the clarifications about canonical URIs in the latest version, removing the broken Auth paragraph, clarifying floating point percents and rotations, etc.
Gotcha, OK.
Right now if I see @context: " http://library.stanford.edu/iiif/image-api/1.1/context.json", I'm going to a set of assumptions about what that server can do. The version is baked into that URI which means if I didn't get that URI from a IIIF server, compatibility is broken.
Yes, and we are always going to make a new context document for a new version, making everything backwards incompatible, making everything a new major version ... thereby defeating the point of any notion of semantic versioning.
What I proposed is that profile and context URIs only reflect the major version, otherwise, yes, it's pointless.
Going forward, we've added the protocol key as an unchanging URI that servers can use as a hook, and then further examine the capabilities of the server based on response from dereferencing the capabilities URI. With that in place, I agree that the URIs changing does not matter (as long as you're following your nose, and not simply making assumptions based on the URI as a key). It is certainly going to be better from now on, regardless of the exact label we give to it. But @context and profile URIs will change every time, thus it's technically backwards incompatible. As will any JSON-LD, or likely any serialization of linked data, based API.
Not if you're following the spec. The only contract the spec is making,
going forward, is that the protocol
URI won't change. If you took a
shortcut and used the context
or profile
URI directly then it's your
client software that's broken, not backwards compatibility.
Sorry, one more addition. The other stable URI in the game here is the Base-URI for your image. Most of the practical linked data applications I can imagine (e.g. the relationship between the Metadata API and the Image API) would be dependent on that URI not changing; not the context or profile.
Very true.
On Mon, Mar 10, 2014 at 9:47 AM, Jon Stroop notifications@github.comwrote:
Sorry, one more addition. The other stable URI in the game here is the Base-URI for your image. Most of the practical linked data applications I can imagine (e.g. the relationship between the Metadata API and the Image API) would be dependent on that URI not changing; not the context or profile.
Reply to this email directly or view it on GitHubhttps://github.com/IIIF/specifications/issues/47#issuecomment-37204594 .
So, thoughts about the URIs only reflecting the major field in the SemVer revision number?
the URIs only reflecting the major field in the SemVer revision number
Yes. Fewer URLs are better. Look how Google fails on maintaining the Google Maps Javascript Reference. The deprecated version URL is broken (404).
Same approach in the Angular Reference, lot of 404s. This is bad.
The other stable URI in the game here is the Base-URI for your image. Most of the practical linked data applications I can imagine (e.g. the relationship between the Metadata API and the Image API) would be dependent on that URI not changing; not the context or profile.
Yes. You would simplify things, if the image and the meta API share the same version.
# current
api/
|__ image/
|__ spec/
|__ compliance/
|__ meta/
|__ spec/
|__ compliance/
# latest 1.x.y
api/
|__ 1/
|__ image/
|__ spec/
|__ compliance/
|__ meta/
|__ spec/
|__ compliance/
Btw, the link
http://library.stanford.edu/iiif/image-api/1.1/context.json
is broken.
Is it considered broken if it never worked in the first place? :crying_cat_face: See #2.
One more comment for versioning. Git allows branches in submodules. You can write the specs in this repository and just include the different branches in the website repository.
Concrete proposal from someone who cares, or close with wontfix ?
I submit #1 in my post way up the page as a proposal.
What are the URIs if there are two versions? It seems pointless to re-number a version to me. I prefer option 3 (eg next version is 2.0.0) which also allows presentation API to synchronize to 2.0.0 at the same time.
However, that's not to say that the next version of presentation API isn't 3.0.0 while image api is 2.0.1 as there might be big changes to one and not to the other. Also search and annotation can't start at 2.0.0.
Unless there's a practical advantage to aliasing that I'm missing?
I'd support that (ie just start). And URIs only reflect the major version.
I agree that there is no benefit in renumbering/aliasing past versions. If we do this we just start.
Seems to me it makes sense only if we do it for all IIIF specs. I assume that is what is imagined?
All specs, individually, right? Eg the search API will start at 1.0.0, at the same time as the presentation and image APIs being at 2.X.Y
If the URIs only reflect the major version, what happens to the previous minor and patch version documents? They get moved to a different URI, but the latest version is always at major? eg: api/image/2/index.html (version 2.1.3) api/image/2/2.1.2/index.html (previous version, 2.1.2) api/image/2/2.1.1/index.html (previous previous version, ... you get the idea)
I think we stick to the major version in the URI for the latest and put the semver number somewhere somewhat prominent near the top of the spec. Once a version is no longer the latest we just use the full semver number (What's the thought behind the extra '2/' above?).
I agree that version numbers are specific to each spec. What I meant by "all IIIF specs" is that we should not apply this scheme to a subset (such as just image), I think we need to be consistent and do semantic versioning for all specs. This might mean that we should expand the number of people we consult to get buy-in from. There are some implications for PR here (e.g. desire to hide breaking changing behind non-semantic versioning).
I would think URIs would be like api/image/2/index -> 302 to api/image/2.1.3/index api/image/2.1.3/index api/image/2.1.2/index etc.
Shall we take it to IIIF-Discuss?
On Fri, Mar 21, 2014 at 9:17 AM, Simeon Warner notifications@github.comwrote:
I agree that version numbers are specific to each spec. What I meant by "all IIIF specs" is that we should not apply this scheme to a subset (such as just image), I think we need to be consistent and do semantic versioning for all specs. This might mean that we should expand the number of people we consult to get buy-in from. There are some implications for PR here (e.g. desire to hide breaking changing behind non-semantic versioning).
I would think URIs would be like api/image/2/index -> 302 to api/image/2.1.3/index api/image/2.1.3/index api/image/2.1.2/index etc.
Reply to this email directly or view it on GitHubhttps://github.com/IIIF/specifications/issues/47#issuecomment-38286007 .
I'm not really sure that's necessary, but I do see @zimeon's point. What about bringing in @snydman first?
Sure. And Tom as well, I think.
On Fri, Mar 21, 2014 at 9:27 AM, Jon Stroop notifications@github.comwrote:
I'm not really sure that's necessary, but I do see @zimeonhttps://github.com/zimeon's point. What about bringing in @snydman https://github.com/snydmanfirst?
Reply to this email directly or view it on GitHubhttps://github.com/IIIF/specifications/issues/47#issuecomment-38287088 .
Am writing it up (unless one of you has already started?)
Done.
For posterity, we added this section to the Image API: https://github.com/IIIF/iiif.io/commit/198646405ffb7a246ee91362e001df12a2646dce#diff-381a219298e27a83caa34173bf7eba82R523
What do you think about following the Semantic Versioning?