How to handle deprecation affecting the writing of ODDs?

[raffazizzi]

Recently (Oct 2023), we deprecated @calendar on a number of elements and in order to enact the deprecation as best as we could, we made changes to the content of att.datable (more info). While the resulting schema will permit @calendar to exist (with a warning) in the same places as before, ODDs will not be able to include @calendar by simply making an element member of att.datable. This change itself did not have a deprecation warning besides a message to TEI-L -- should it have a more formal warning? Should it last as long as other schema changes?

In the past we have been making these changes without deprecation. See for example the release notes for 4.6.0: https://www.tei-c.org/release/doc/tei-p5-doc/readme-4.6.0.html

Changes to classes The model.glossLike class (which contained altIdent, equiv, and gloss) has been renamed to model.identSynonyms.

This change was not preceded by a deprecation period.

[sydb]

In addition to the class change made for 4.6.0 that @raffazizzi points out above, many other such changes have been made without a deprecation period. None of the following, each of which introduced a change that would likely require changes to some ODD files, were deprecated or (in most cases) even announced in advance:

• Release 1.9: “All elements have been changed to make them explicit members of the att.global attribute class, rather than having this done by special-case processing during the build procedure. This means that any ODD which defines elements in the TEI namespace will have to explicitly add att.global to them.”
• Release 2.2.0: “The model.glossLike class was subdivided” into model.glossLike, model.descLike, and model.certLike.
• Release 2.3.0: att.sourced renamed to att.edition.
• Release 2.3.0: <abbr> and <title> now get their @type from att.typed.
• Release 2.6.0: Several elements that had a locally defined @type become members of att.typed instead.
• Release 2.8.0: @rend, @style, and @rendition moved from att.global to the new att.global.rendition.
• Release 3.0.0: The @hand attribute was moved from att.damaged, att.textCritical, and att.transcriptional to a new att.written.
• Release 3.3.0: @lemma and @lemmaRef moved to a new att.linguistic.
• Release 3.5.0: <witDetail> removed from model.noteLike.
• Release 4.0.0: model.resourceLike revised and renamed model.resource.
• Release 4.1.0: “The class membership of <q> has been changed. In the course of this, the element class model.qLike was renamed to model.attributable.”
• Release 4.2.0: att.translatable moved from the TEI Infrastructure module to the Documentation Elements module.
• Release 4.2.0: @predicate of <model> replaced with a reference to the new att.predicate.
• Release 4.3.0: @where of <event> moved to the new att.locatable.

Or the following, which might have required a change to some ODD files:

• Release 2.0.2: <geo> added to att.declaring
• Release 2.1.0: @wit removed from <rdgGrp>
• Rekease 2.2.0: Creation of att.milestoneUnit
• Release 3.5.0: att.tableDecoration moved from the tei module to the figures module.
• Release 3.6.0: <fLib>, <fsDecl>, <fsdLink>, and <fvLib> become members of the new model.fsdDeclPart.
• Release 4.5.0: In order to allow <ab> to nest inside itself, added a new macro.abContent and model.paraPart.

My point is that the TEI has never deprecated ODD changes before (by which I mean changes that may require changes to a schema specification, but would not, by themselves, require changes to encoded transcriptions); rather, such changes are simply instituted without warning above and beyond the release notes. And, to my (possibly faulty) recollection, no one has complained about the lack of a deprecation period.

I believe that our commitment to, whenever feasible, deprecate changes that break backwards compatibility (the “Birnbaum Doctrine”) is intended to apply to changes that affect the validity or correctness of existing transcriptions, not existing schema specifications.

[sydb]

I realize I should explain why I think we should not work on a deprecation mechanism for changes to classes. In short, it would be hard to do. Really hard, perhaps impossible. And (as alluded to above) the benefit to ODD writers is pretty small. (Remember, as a general rule, no one has to update their ODD to match the latest version of the Guidelines; they very well may want to, but the pressure to switch is generally internal to their project, not from the outside world. I.e., it is very rare that an upgrade to a newer version is required due to an old one breaking. Not sure it has ever happened.) Thus the cost-benefit analysis makes it clear (at least to me, although to be fair, I may be overly pessimistic) that we should continue with our admittedly somewhat cavalier attitude about breaking ODD backwards compatibility. The benefit to ODD writers would be real, but overall pretty minor. The cost, however, would be very high: I really believe that we (Council) would get a lot less done during the ½–2 years spent developing such a mechanism, and then a moderate amount less done every year thereafter (because implementing the system would take time & effort, too). We are already really far behind as it is.</rant>

All that said, being better about announcing potential ODD-breaking changes as such in the release notes might have a much better cost-benefit ratio. (Perhaps we should even make a habit of separating out those changes that we anticipate might break some ODDs into a separate section.)

P.S. I have not really thought through the mid-level solution of a boutique <constraintSpec> for each possible ODD-breaking change. I suspect I may be against the idea, but it is much more reasonable than a generic mechanism.

[raffazizzi]

Given that's been a week and there's been no comments from the community (either here or on the email list), I think you're right, @sydb. No need to give advance warning for these changes. We just need to continue to list them on the release notes.

[raffazizzi]

At 2023-11-10 council call we agreed to not deprecate these changes and to continue documenting them in the release readme.

Additionally, we want to document this practice better, so before we close this issue we will need to update TCW documents as follows.

• [x] TCW 27 should describe that deprecation is not needed in these cases
• [x] TCW 22 should remind the README writer (typically the council chair) to mention these ODD-breaking changes in its own section of the README