search

IIIF / api

Source for API and model specifications documents (api and model)
http://iiif.io/api
106 stars 54 forks source link

Follow Semantic Versioning #47

Closed doktorbro closed 10 years ago

doktorbro commented 10 years ago

What do you think about following the Semantic Versioning?

jpstroop commented 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:

  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, @zimeon, @snydman: thoughts?

azaroth42 commented 10 years ago

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 .

azaroth42 commented 10 years ago

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 .

jpstroop commented 10 years ago

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.

azaroth42 commented 10 years ago

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

jpstroop commented 10 years ago

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.

jpstroop commented 10 years ago

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.

azaroth42 commented 10 years ago

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 .

jpstroop commented 10 years ago

So, thoughts about the URIs only reflecting the major field in the SemVer revision number?

doktorbro commented 10 years ago

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/
doktorbro commented 10 years ago

Btw, the link

http://library.stanford.edu/iiif/image-api/1.1/context.json

is broken.

jpstroop commented 10 years ago

Is it considered broken if it never worked in the first place? :crying_cat_face: See #2.

doktorbro commented 10 years ago

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.

azaroth42 commented 10 years ago

Concrete proposal from someone who cares, or close with wontfix ?

jpstroop commented 10 years ago

I submit #1 in my post way up the page as a proposal.

azaroth42 commented 10 years ago

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?

jpstroop commented 10 years ago

I'd support that (ie just start). And URIs only reflect the major version.

zimeon commented 10 years ago

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?

azaroth42 commented 10 years ago

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)

jpstroop commented 10 years ago

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?).

zimeon commented 10 years ago

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.

azaroth42 commented 10 years ago

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 .

jpstroop commented 10 years ago

I'm not really sure that's necessary, but I do see @zimeon's point. What about bringing in @snydman first?

azaroth42 commented 10 years ago

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 .

azaroth42 commented 10 years ago

Am writing it up (unless one of you has already started?)

azaroth42 commented 10 years ago

Done.

jpstroop commented 10 years ago

For posterity, we added this section to the Image API: https://github.com/IIIF/iiif.io/commit/198646405ffb7a246ee91362e001df12a2646dce#diff-381a219298e27a83caa34173bf7eba82R523