Practices no longer recommended or now deprecated

Policy

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, at times 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"

According to 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.

To do

1. Decide remaining questions

A. Since we are no longer using @status='deprecated', should we remove it as a legal value of this attribute in att.identified? It's odd to include it here if we won't be using it. Note that we only added this value recently, when implementing FR 1933481.

Syd deprecated the value of "deprecated" at revision 12101 and asked whether to deprecate the whole attribute. Kevin suggested on tei-council on 2013-05-16 that we in fact deprecate the whole attribute. (Kshawkin 17:09, 16 May 2013 (EDT))

B. For deprecations (things we plan to remove), we already decided to try to remember to mention them in release notes. But will we also do any of the following?

1. list them on a wiki page (this one?)
2. create a new tracker item for each
3. announce each on TEI-L

I suggest we not create tracker items and therefore simply close bug 3435326. If Council has already decided to deprecate, we don't need any feedback, and we can use @validUntil to track planned deprecations. (Kshawkin 23:10, 18 April 2013 (EDT))

I think the Guidelines themselves should contain an automatically-generated page or chapter listing deprecated items along with their validUntil dates. The Guidelines are most people's primary source of information; we can't assume they read the TEI-L list, read the release notes or go to the wiki. (Mholmes)

2. Create a new tcw with the policy, plus answers to the remaining questions, for future reference

Once Council reviews that the intent from the Providence meeting has been correctly represented, KH will create this document (as originally requested in Oxford).

3. Modify release building procedure

KH will add a step to tcw22 to say to grep the specs looking for @validUntil. For any values that are dates that have passed, you should go ahead and carry out the deprecation.

Alternatively, SR suggested that we might modify the build process so that it gives an error if the value of any @validUntil has passed, forcing us to complete the deprecation in order to get a successful build.

4. Add handling of @validUntil to stylesheets for generating Guidelines

With at least one revision to test with (so implement something from the next section of this document as a test), SR will:

• add code to stylesheets to display "Deprecated: valid until YYYY-MM-DD" in specs when @validUntil is present.
• add rendering of @validUntil in specLists. (Currently @status does not display in specLists!)

For now leave handling of @status in place in case a release is made before all specs are updated.

5. Recent "deprecation" practices to be reviewed

For all of the following tickets ...

• deprecate <relationGrp>
• dictionary entries with a single <sense>
• Use @ref instead of @key
• <altIdentifier> is deprecated within <msPart>
• where to put <idno> within <biblStruct>
• Deprecation of "magic token" attributes
• deprecate use of gram except as a child of gramGrp
• @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> (Note: deprecation will be noted in the Guidelines when FR 3556778 is implemented.)
• add @unit to <biblScope>, and soft-deprecate @type

... we need to make sure they've been handled according to the above policy.

KH will do the following:

• If the spec has a @status, remove it. If appropriate according to the above policy, add a @validUntil with a value corresponding to two years after the date that the @status was added.
• If the spec has no @status but it should have a @validUntil according to the above policy, add @validUntil with a value that is two years from the current date.
• If it's a "no longer recommended" practice, make sure there's appropriate text in <remarks>.
• For deprecations, reopen the ticket if necessary and assign to SB with a note to add a Schematron warning.

SB will do the following:

• Add a Schematron warning for the "no longer recommended" practices.

6. Remove @status='deprecated' in stylesheets

SR will change the stylesheets to remove display of "(deprecated)" for @status='deprecated' since this is no longer needed.