Procedure for handling practices that are no longer recommended or deprecated
At its April 2013 face-to-face meeting in Providence, the Technical Council agreed to the following policy for handling practices that are "no longer recommended" or "deprecated".
No longer recommended
While the TEI Guidelines often offer more than one way of encoding a particular phenomenon, in this case the Council agrees to identify a preferred method without making any definite plans to remove the non-preferred way from the Guidelines. In this case:
- The <remarks> element is used in the spec to indicate the preferred practice.
- The prose in one or more chapters is revised to indicate this preferred practice. Examples showing the non-preferred practice are maintained but preferably only in the section of the Guidelines where that element or attribute is discussed, not in passing elsewhere.
Following the Birnbaum doctrine, the Council has made the serious decision to break backwards compatibility by changing the content model of an element or class to remove an element or attribute, or to remove an element or attribute entirely from the Guidelines. In this case:
- The appropriate spec is modified to add @validUntil on the appropriate <elementSpec> , <classRef> , or <attDef> elements. The value of @validUntil shall be no sooner than two years from the date of the change (thus guaranteeing at least one year from the release in which the deprecation is announced to the change in which the feature disappears).
- A Schematron warning is added to the spec.
- Any examples of the deprecated practice are removed from the Guidelines, and any prose recommending them is reworded as appropriate.
- We will try to remember to include a mention of the deprecation in the release notes created for the following release.
After the date specified in @validUntil:
- The element or attribute is actually removed from the spec.