Practices no longer recommended or now deprecated

Policy

http://www.tei-c.org/Activities/Council/Working/tcw27.xml

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).

TCW27 was created on 16 May 2013. (Kshawkin 15:46, 16 June 2013 (EDT))

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 on tei-council on 2013-04-19 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.

I see that SR's suggestion has already been implemented! (Kshawkin 00:54, 20 June 2013 (EDT))

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 "deprecations" to be reviewed

For all of the following tickets, re-read the ticket and determine how it fits in the above policy. Ignore uses of terms like "deprecate" and "no longer recommended" because they are likely not used in the reserved sense now defined in TCW27.

recent "deprecation"	if interpreted according to TCW27
deprecate <relationGrp>	deprecated on 2012-06-17
dictionary entries with a single <sense>	no longer recommended
Use @ref instead of @key	no longer recommended
<altIdentifier> is deprecated within <msPart>	deprecated on 2011-04-24
where to put <idno> within <biblStruct>	Intent unclear, but I think we deprecated on 2012-10-02. (We didn't leave any counter-examples in the Guidelines, and we talked about wanting to remove it. See r10889 from 2012-10-02.)
Deprecation of "magic token" attributes	(still open)
deprecate use of gram except as a child of gramGrp	deprecated on 2011-12-05
@targets deprecated on <join> -- This was implemented at revisions 8763, 8807, and 8808 (but can't find a mention in any minutes, a ticket, or discussion of this on tei-council).	deprecated on 2011-03-20
@form deprecated on <quotation> (Note: deprecation will be noted in the Guidelines when FR 3556778 is implemented.)	deprecated on 2012-04-28 (Don't see how the other ticket relates!)
add @unit to <biblScope>, and soft-deprecate @type	deprecated on 2012-12-17

Then 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.

At revision 12284 and revision 12285, KH has:

• deprecated @status on att.identified
• replaced any past uses of @status with @validUntil, with a date that's two years from the date that the "deprecation" happened, or three months from today, whichever is later
• added @validUntil where missing except in the following cases:
  • https://sourceforge.net/p/tei/feature-requests/294/#5737
  • https://sourceforge.net/p/tei/feature-requests/383/?limit=10&page=1#bbe8
  • https://sourceforge.net/p/tei/bugs/288/?limit=10&page=3#99f0
• added appropriate text in <remarks>

In addition, I have added notes to ticket #459 about places where Schematron warnings are needed (instead of reopening tickets as originally planned).

SB will do the following:

• Add a Schematron warning for the "no longer recommended" practices. See #459 warn user of dropped constructs.
• Figure out how to solve the three tickets above that Kevin couldn't solve. See #486 deprecating members of a content model.

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.

I've created https://sourceforge.net/p/tei/feature-requests/463/ and assigned to SR. (Kshawkin 23:03, 20 June 2013 (EDT))