Practices no longer recommended or now deprecated

From TEIWiki
Revision as of 04:43, 18 January 2013 by Kshawkin (talk | contribs) (→‎Proposals to clarify practice: many more proposals culled from tei-council)
Jump to navigation Jump to search

Over the course of a few TEI Technical Council meetings from 2010 to 2012, Council members agreed to establish two different deprecation mechanisms for practices in the Guidelines which are to be phased out at some point. (See a bit of history of the technical implementation.) Here are links to particular meetings where this was discussed:

Recent practice

Soft deprecation

"Soft deprecation", sometimes called a "health warning", is a statement in the Guidelines that a practice is no longer recommended. However, no timeline is established for removing particular elements or attributes. There is currently no mechanism to find such statements in the Guidelines to actually remove them.

Examples:

Hard deprecation

We make adjustments to the prose of the Guidelines, and status="deprecated" is inserted in the Guidelines ODD(s) to mark the deprecated element or attribute.

Examples:

Proposals to clarify practice

Kevin's

For all deprecations of elements or attributes, we would use status="deprecated" in the appropriate place in the appropriate spec(s) and, where appropriate, add prose to the Guidelines explaining that the practice is no longer recommended. We would use some sort of mechanism, such as SF tickets, for tracking work that remains to be done in the future.

For soft deprecations, we would remove examples in the Guidelines that include an element or attribute in passing but leave any examples that illustrate this element or attribute in particular. No timeline would be established for removing the element or attribute from the Guidelines.

For hard deprecations, we would remove all examples of an element or attribute found in the Guidelines and plan to modify the appropriate spec(s) one year from the time of implementation of the hard deprecation.

Sebastian's

[W]hen we decide to deprecate something, we move it immediately to the new Deprecated module. One day, we delete it even from there, but for a few years you can still use it if you want, with some extra barrier (making a new schema with that module). (User:Rahtz)

This is a cunning way of circumventing/subverting the Birnbaum Doctrine. Whereas we used to say "no changes made in the TEI scheme will invalidate your document", we're now saying "no changes made in the TEI

scheme will invalidate your document, so long as you include the "deprecated" module in your schema". Will it work though? Suppose we decide that we want to rename attribute @target to @url and deprecate @target passim (stranger things have happened). We make the change in P5. We provide alternative definitions for all the elements which used to use @target in which they still do and bung them in the deprecated module. So far so good. But now suppose we make some other change to one or more of those elements, which doesn't involve any deprecation but which is a straightforward bug fix. Do we apply this fix to the deprecated version as well? What if (as you suggested earlier) one or more of these elements gets a new attribute ? (User:LouBurnard/User:Lou)

We'd find some mechanism in the deprecated module to work around these issues. Definitely lots of details to work out. My assumption is that Deprecated would be like a customization we pre-applied before any other customization. So things like element X getting a new attribute is fine, as the module would just be modifying it to add (back) a deleted attribute (User:Rahtz)
And I still don't know what we do about "stylistic deprecation" -- where we say this element is permitted in the content model, but you should really only use it in this particular way (e.g. @target on <locus> ) (User:LouBurnard/User:Lou)
Sebastian seemed interested using Schematron warnings for this.
I don't really think this is much of a problem in real life, as long as the Guidelines are chock-full of good examples of what we believe people should be doing. (Of course they're still a bit lacking in that area, but we are committed to fixing that.) Weird uses which are schema-compliant but undesirable tend to arise mainly because there's no useful example for people to follow. The elementSpec for <locus> is good in this respect: there are two examples and a note explaining the issue.
If we give advice and people choose to ignore it, that's up to them, really. We can't police everything. (User:Mholmes)
I think the value of deprecation is precisely that people can carry on using the deprecated attribute (vel sim) without having to think about it especially, just receiving a gentle warning (in the Guidelines, I guess) rather than that people have to speifically re-introduce a deprecation module to their schema to keep the attribute around. In general people who want to be this proactive with their schemas are the ones who will take account of deprecation the soonest. (User:GabrielBoard/User:Gabriel Bodard)

Martin's

There should be just one type of deprecation. After a set time limit for all deprecations (12 months? 2 years?), we move the feature to a module called "backwardcompatibility" which is not included by default. Perhaps we would use source@mode for this. Notes that we would need to maintain it. For example, in renaming att.sourced to att.edition, a backwardCompatibility module that attempted to restore a deleted attribute to att.sourced would fail because it's not there any more.

Yes, it would take some careful thought on how to do it. But it seems worth a try, a maintained schema which confirmed Birnbaumites could access. (User:Rahtz)
I think that's just silly. How would this be different from (or more useful than) a previous version of the schema in which the various deprecations had not yet taken effect? I say when things are removed, they are removed. End of. (User:LouBurnard/User:Lou)
Because the schema would also include new things. the scenario Is that I need t keep using @targets cos my tool supports that, and I can't afford to change. I have my loads of docs using that markup. But I also want to use the new @magic markup. (User:Rahtz)
It enables you to take advantage of new additions and changes to the schema, without having to abandon your beloved @key (or whatever it is). (User:Mholmes)
But chances are my old tool won't be able to do anything with the new @magic so why would I bother? Or if I want to make it do so, then I might as well teach it not to use old @targets. (User:LouBurnard/User:Lou)

While tei_all would not include backwardCompatibility, we could provide an additional customization that does include it.

FWIW, I think a "backwards compatibility" module would be over-engineering. If people want to recover something we've removed, åthere are other and simpler ways of doing so. (User:LouBurnard/User:Lou)

Gabby's

I vote for the red "Deprecated" flag in the element/class Spec page.

James's

Marked as deprecated on the reference page preferably with a note with date or similar at which it will be removed, a schematron warning rule set up, and the <desc> changed to be prefixed with 'DEPRECATED: '. (Changing the <desc> will result in people noticing this in tooltips in software like oXygen, make it that much more evident on the reference page, and where specDesc has been used to pull in the description elsewhere.) (User:JamesC)

(fill in yours here)

To be resolved

For both soft and hard deprecation, a bug or feature request ticket is sometimes created -- or an existing bug or feature request is reassigned to the "Deprecated" category.

Also, should we adopt any of the practices suggested on the talk page?

Retrieved from "https://wiki.tei-c.org/index.php?title=Practices_no_longer_recommended_or_now_deprecated&oldid=11596"