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.

[triplingual]

I don't know how much I'm an outlier here (and in multiple ways), but I still wish I could see the differences more quickly. However, it could be that only those of us fairly well steeped in IIIF and maybe even mostly those of us working on the cookbook who care about diffing. I don't know how to find this out. Since I'm inclined to think the people who care about that are also people we can expect to have or acquire facility with git/GitHub, maybe there's a way to link to a diff for those of us who care. I am less inclined than I think I was to have a diff in the recipe itself and certainly don't think we can take on the maintenance of writing up all the differences.

[triplingual]

What would a recipe look like that only had one version?

(Putting these things as separate comments so they can be more easily addressed separately.)

[glenrobson]

Note underlying directory structure for a v4 recipe: https://github.com/IIIF/cookbook-recipes/tree/v4/recipe/0001-mvm-image/v4

• Question what to do about a v4 only recipe? (echoing Trip's comment above)
• We could move the v3 recipe to a v3 directory but this would change the manifest id unless there was a redirect.

Further work

• [ ] Look at some kind of javascript to identify version of a recipe and include a v3 note so its not a manual process.
• [ ] Investigate if there is a way to automated diffs on manifests...
• [x] freeze the "Version 3" and "Version 4" headers
• [x] Look at making the styling more prominent for the one you selected. Also when you arrive at a recipe ensure the one you are looking is highlighted.

[glenrobson]

See how easy this structure would be:

viewers:
  - Mirador
     - 3
     - 4
  - UV

Look at what to do with code like iiif-prezi3.

[glenrobson]

• [ ] Change Version 3 to Presentation API version 3 to make it clear maybe on multiple lines.
• [ ] Add a note about versions on the main page of the cookbook.

[elynema]

Questions from working on my 2 recipes:

• How to handle recipe name changes from v3 to v4?
  • v3: “Using Caption and Subtitle Files with Video Content”
  • v4: “Using Caption Files with Video Content”
• How to handle v4 recipes that never had a v3 version created? ex: 0253.

[glenrobson]

• [ ] What do we do with the viewer matrix? Too seperate pages? Javascript slider for v3 and v4
• [x] CSS issue left aligned titles and missing space between first heading.