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.

Deprecated

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).
  • An announcement is sent to TEI-L that the Technical Council has decided to depreacate elementName and will drop it as early as YYYY-MM-DD. If anyone strongly objects, they should reply to the list so that the Council might reconsider.
  • 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.

Last recorded change to this page: 2014-01-01  •  For corrections or updates, contact web@tei-c.org