search

distributed-text-services / specifications

Specifications for the DTS API
https://w3id.org/dts
28 stars 9 forks source link

Breaking changes, versioning and reference implementations #245

Closed geoffroy-noel-ddh closed 6 months ago

geoffroy-noel-ddh commented 6 months ago

I believe a new version of the spec has recently been released. I didn't find links to the previous version of the spec to compare and confirm, but I have the impression that the new version introduces breaking changes. Is that the case?

If so:

  1. are the breaking changes listed somewhere?
  2. are the reference implementations listed on the site already compliant with the new versions or are they deprecated? If so, it would help to clarify for the users when they look at them to understand the spec or develop tools around them. Otherwise it might create confusion with apparent contradiction between specs and implementations.
  3. is there any implementation that currently conform to the new spec? An "official" demo of a minimal client & server would be extremely useful to assist with adoption and migration. I understand that it is demanding to maintain it.
PonteIneptique commented 6 months ago

Hi Geoffroy :)

  1. We need to add a page for Changes, but yes, we added a list of changes in https://github.com/distributed-text-services/specifications/pull/238

  2. The main page needs to be updated, as the reference implementation are now all based on implementations.

  3. We are working on it, but no, as the new specs are completely new, we don't have everything else yet :)

geoffroy-noel-ddh commented 6 months ago

Thanks for the prompt response Thibault.

From a user perspective who's very keen on your spec (as I think it's extremely valuable for sustainability of a lot of DH projects) I would definitely recommend to keep the old spec available to help users with the transition, highlight breaking changes within the new specs, perhaps even keep supporting some old features for a while before dropping them in a later release (e.g. ?id= -> ?resources= is a brutal one that may break clients!).

  1. do you mean they are all based on the old spec?

  2. I think I have mentioned this before in passing, I've built a prototype web viewer that can interact with any DTS source. I successfully tried it on your reference DTS servers (albeit with interesting discrepancies). It is currently embedded in a specific project but the aim for our team was to have a baseline, reusable viewer for legacy projects (so the old edition remain alive on the web). A sort of Universal Text Viewer (like those available for IIIF, which are not bound to a specific source). That approach in itself could be an excellent way to a) demonstrate the importance of your spec b) test new server implementations (if they work with a Universal viewer, it's a good sign that they comply with the spec, especially while there is not yet a formal way to validate/lint DTS responses).

PonteIneptique commented 6 months ago
  1. Versions are now kept :) Links are available within the API Documentation.
  2. We clarified that the current implementation are not up to date with the 1-alpha (some might actually be with 1-draft1, but unfortunately, because we worked badly on that, the docs of 1-draft1 is complex to go back to...)
  3. It's fantastic. We would love to advertise it on our main page :)
geoffroy-noel-ddh commented 6 months ago

Great, thanks for the clarifications!