Practices no longer recommended or now deprecated

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:

• April 2010 meeting in Dublin
• April 2011 meeting in Chicago
• November 2011 meeting in Paris
• April 2012 meeting in Ann Arbor

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:

• deprecate <relationGrp> -- See the resulting note on definition of relationGrp
• dictionary entries with a single <sense>
• Use @ref instead of @key
• <altIdentifier> is deprecated within <msPart> -- Perhaps this should have been done as a hard deprecation. We didn't specify.
• where to put <idno> within <biblStruct>

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:

• deprecate use of gram except as a child of gramGrp -- Kevin is waiting on clarification on whether to create a new ticket and needs guidance on where to put status="deprecated".
• @targets deprecated on <join> -- This was implemented at revisions 8763 and 8808 (but can't find a mention in any minutes, a ticket, or discussion of this on tei-council).
• @form deprecated on <quotation> -- While the deprecation note appears in red in the element definition, it doesn't appear at all when the element is referenced in the prose of the Guidelines (Note: deprecation will be noted in the Guidelines when FR 3556778 is implemented.)
• add @unit to <biblScope>, and soft-deprecate @type -- It said to do "soft, soft deprecation", but use of @status feels like the most clear way to communicate this. This is one of the many things LB and KH need to resolve in our tcw on deprecation.

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.

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.

• We might change our practice to create a new type of tracker item instead of using a category.
• Should we use this category only for soft or only for hard deprecation? Should "closed" mean that the practice has been deprecated or, for a hard deprecation, should it mean that the element or attribute has actually been removed?

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