Follow Semantic Versioning #47

doktorbro · 2014-03-08T20:29:03Z

What do you think about following the Semantic Versioning?

jpstroop · 2014-03-10T13:59:23Z

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:

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.
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.
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 · 2014-03-10T15:20:59Z

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:

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//issues/47#issuecomment-37184436
.

azaroth42 · 2014-03-10T15:22:08Z

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:

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//issues/47#issuecomment-37184436
.

jpstroop · 2014-03-10T16:21:47Z

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 · 2014-03-10T16:28:12Z

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 · 2014-03-10T16:35:27Z

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 · 2014-03-10T16:47:36Z

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 · 2014-03-10T17:07:48Z

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//issues/47#issuecomment-37204594
.

jpstroop · 2014-03-10T17:55:53Z

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

doktorbro · 2014-03-10T20:25:34Z

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

experimental version: /3.exp/reference
release version (3.9): /reference
deprecated version (3.8): /3.8/reference

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 · 2014-03-10T21:33:30Z

Btw, the link

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

is broken.

jpstroop · 2014-03-10T21:36:19Z

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

doktorbro · 2014-03-10T21:54:10Z

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 · 2014-03-20T21:36:23Z

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

jpstroop · 2014-03-20T22:49:56Z

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

azaroth42 · 2014-03-20T22:57:38Z

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 · 2014-03-20T23:03:02Z

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

zimeon · 2014-03-21T03:28:09Z

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 · 2014-03-21T15:07:15Z

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 · 2014-03-21T15:12:42Z

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 · 2014-03-21T15:17:30Z

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 · 2014-03-21T15:24:43Z

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//issues/47#issuecomment-38286007
.

jpstroop · 2014-03-21T15:27:22Z

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

azaroth42 · 2014-03-21T15:37:50Z

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//issues/47#issuecomment-38287088
.

azaroth42 · 2014-03-21T16:04:13Z

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

azaroth42 · 2014-04-29T20:51:12Z

Done.

jpstroop · 2014-04-29T21:36:56Z

For posterity, we added this section to the Image API: 1986464#diff-381a219298e27a83caa34173bf7eba82R523

This was referenced Mar 20, 2014

Change website references to the iiif.io domain #3

Closed

Confirm URIs for compliance docs (which are also capabilities documents) #51

Closed

jpstroop mentioned this issue Apr 28, 2014

Make compliance level URIs consistent #71

Closed

azaroth42 closed this as completed Apr 29, 2014

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Follow Semantic Versioning #47

Follow Semantic Versioning #47

doktorbro commented Mar 8, 2014

jpstroop commented Mar 10, 2014

azaroth42 commented Mar 10, 2014

azaroth42 commented Mar 10, 2014

jpstroop commented Mar 10, 2014

azaroth42 commented Mar 10, 2014

jpstroop commented Mar 10, 2014

jpstroop commented Mar 10, 2014

azaroth42 commented Mar 10, 2014

jpstroop commented Mar 10, 2014

doktorbro commented Mar 10, 2014

doktorbro commented Mar 10, 2014

jpstroop commented Mar 10, 2014

doktorbro commented Mar 10, 2014

azaroth42 commented Mar 20, 2014

jpstroop commented Mar 20, 2014

azaroth42 commented Mar 20, 2014

jpstroop commented Mar 20, 2014

zimeon commented Mar 21, 2014

azaroth42 commented Mar 21, 2014

jpstroop commented Mar 21, 2014

zimeon commented Mar 21, 2014

azaroth42 commented Mar 21, 2014

jpstroop commented Mar 21, 2014

azaroth42 commented Mar 21, 2014

azaroth42 commented Mar 21, 2014

azaroth42 commented Apr 29, 2014

jpstroop commented Apr 29, 2014

Follow Semantic Versioning #47

Follow Semantic Versioning #47

Comments

doktorbro commented Mar 8, 2014

jpstroop commented Mar 10, 2014

azaroth42 commented Mar 10, 2014

azaroth42 commented Mar 10, 2014

jpstroop commented Mar 10, 2014

azaroth42 commented Mar 10, 2014

jpstroop commented Mar 10, 2014

jpstroop commented Mar 10, 2014

azaroth42 commented Mar 10, 2014

jpstroop commented Mar 10, 2014

doktorbro commented Mar 10, 2014

doktorbro commented Mar 10, 2014

jpstroop commented Mar 10, 2014

doktorbro commented Mar 10, 2014

azaroth42 commented Mar 20, 2014

jpstroop commented Mar 20, 2014

azaroth42 commented Mar 20, 2014

jpstroop commented Mar 20, 2014

zimeon commented Mar 21, 2014

azaroth42 commented Mar 21, 2014

jpstroop commented Mar 21, 2014

zimeon commented Mar 21, 2014

azaroth42 commented Mar 21, 2014

jpstroop commented Mar 21, 2014

azaroth42 commented Mar 21, 2014

azaroth42 commented Mar 21, 2014

azaroth42 commented Apr 29, 2014

jpstroop commented Apr 29, 2014