Difference between revisions of "Practices no longer recommended or now deprecated"
Jump to navigation
Jump to search
m (wiki markup) |
(rewrote now that I've realized how inconsistent our practice for "deprecation tickets" has been) |
||
| Line 8: | Line 8: | ||
== Soft deprecation == | == 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 | + | "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: | Examples: | ||
| Line 21: | Line 19: | ||
== Hard deprecation == | == Hard deprecation == | ||
| − | + | We make adjustments to the prose of the Guidelines, and we insert @status=deprecated is inserted in the Guidelines ODD(s) to mark the deprecated element or attribute. | |
Examples: | Examples: | ||
* [http://purl.org/tei/bug/3376456 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". | * [http://purl.org/tei/bug/3376456 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". | ||
| − | * [http://www.tei-c.org/release/doc/tei-p5-doc/en/html/ref-join.html @targets deprecated on <join>] -- This was implemented at revisions [http://tei.svn.sourceforge.net/viewvc/tei/trunk/P5/Source/Specs/join.xml?r1=8457&r2=8763 8763] and [http://tei.svn.sourceforge.net/viewvc/tei/trunk/P5/Source/Specs/join.xml?r1=8763&r2=8808 8808] (but can't find a mention in any minutes, a ticket, or discussion of this on tei-council). | + | * [http://www.tei-c.org/release/doc/tei-p5-doc/en/html/ref-join.html @targets deprecated on <join>] -- This was implemented at revisions [http://tei.svn.sourceforge.net/viewvc/tei/trunk/P5/Source/Specs/join.xml?r1=8457&r2=8763 8763] and [http://tei.svn.sourceforge.net/viewvc/tei/trunk/P5/Source/Specs/join.xml?r1=8763&r2=8808 8808] (but can't find a mention in any minutes, a ticket, or discussion of this on tei-council). |
| + | |||
| + | == 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. | ||
| + | |||
| + | * [http://purl.org/tei/bug/3435326 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? | ||
[[Category:Council]] | [[Category:Council]] | ||
Revision as of 22:44, 4 August 2012
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
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 of @key
- <altIdentifier> is deprecated within <msPart> -- Perhaps this should have been done as a hard deprecation. We didn't specify.
Hard deprecation
We make adjustments to the prose of the Guidelines, and we insert @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).
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?
