How to handle IIIF v3 and v4 recipes

[glenrobson]

How should we handle the introduction of IIIF version 4? Should we:

• Re-write all recipes to have both v3 and v4?
• Should we have one recipe with two examples. Cover difference in recipe?
• Other options

[glenrobson]

Another option is to stop writting v3 recipes at a point and then start a new v4 cookbook. Gradually start converting v3 recipes and link between 3 & 4.

[stephenwf]

Is there a draft of V4, or some expected breaking changes?

If the differences are likely to be very minimal, we could have tabs like this for the JSON examples:

[mathewjordan]

Is there a draft of V4, or some expected breaking changes?

If the differences are likely to be very minimal, we could have tabs like this for the JSON examples:

This approach is very logical if use cases remain the same.

[triplingual]

The tabs idea is good, but I don't know how it would accommodate textual changes. Since the cookbook readership is assumed to range from total newbies to expert users, we may need to call out a small difference or want to go a little deeper on the technical consequences of a situation where there are choices. As well, we do talk about viewers/clients sometimes and will want to be sure that text mentioning them as a class or as specifics is clear for versions. V3 recipes will need maintenance, but that maintenance might diverge from V4 creation and maintenance.

[triplingual]

(Separate, but might be worth putting into this Issue: Maybe this moment is the time to break with UV v3 and incorporate testing recipes with UV v4 as part of the prezi 4 transforms?)

[kirschbombe]

I think this will very much depend on whether there are any foundational changes that would impact our current recipes. I don't think there will be much, but if nothing changes for a recipe, then we might be able to simply label it v3 + v4. Where there are breaking changes, I think it makes sense to keep the two recipes separate as it could get confusing to cover both in the same recipe. Of course, some recipes/use cases will be v4 only. v3 will still be in use for the foreseeable future, so we shouldn't overwrite/update existing recipes.

[glenrobson]

Should we add a section in v4 recipes to say the changes with v3?

Not all recipes will have a version in 3 e.g. 3d

Maybe a warning or just where the different is subtle and could be missed.

We didn't do this for v2 or v3.

Can we automate the diff between recipes?

[ksclarke]

I think a section in v4 recipes, highlighting what the differences are with v3, would be useful and that it's okay to not have it when not relevant (e.g., 3d). If you wanted to be explicit, you could make a note that this is a new feature so no corresponding v3 recipe exists, but I don't think that's necessary, personally.

[sdellis]

Given that collections and manifests must support the presentation of referenced resources that could be in any version, yet presented as a single entity, I think it would be most helpful to have recipes and fixtures for all the API versions.

[glenrobson]

Here is a prototype for a v3 and v4 recipe:

https://preview.iiif.io/cookbook/v4/recipe/0001-mvm-image/

Comments / thoughts very welcome. (Note I noted some issues in the pull request)

[triplingual]

Three initial thoughts. (I'm looking on mobile, for what that's worth.)
For one thing, when the recipe comes up initially, there's no top-level visual indication whether I'm looking at v3 or v4. When I actively select a version, the appropriate header is indicated. That seems like one good starting indicator as well.
At the manifest, there's a link to the iiif-prezi3 code sample that is invariant between the v3 and v4 recipe versions. Is that correct?
The inclusion of "(v3)" in links varies, and we should think through the semantics and UX of that.

[triplingual]

Oh, that's odd — just looked at it on my laptop now and the links to other recipes don't have the (v3) anywhere. Which should I be seeing?

[triplingual]

It would be useful to freeze the "Version 3" and "Version 4" headers as we do with the viewer matrix so that a reader can see throughout the recipe that version they are looking at.