Difference between revisions of "Practices no longer recommended or now deprecated"

From TEIWiki
Jump to navigation Jump to search
(→‎Soft deprecation: added bug 3590818 (bug 476))
(completely rewrote based on discussion in Providence)
Line 1: Line 1:
−
Over the course of a few [[Council|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 [http://purl.org/tei/fr/1933481 a bit of history of the technical implementation].) Here are links to particular meetings where this was discussed:
+
== Policy ==
  
−
* [http://www.tei-c.org/Activities/Council/Meetings/tcm45.xml April 2010 meeting in Dublin]
+
At its April 2013 face-to-face meeting in Providence, the [[Council|Technical Council]] agreed to the following policy for handling practices that are "no longer recommended" or "deprecated".
−
* [http://www.tei-c.org/Activities/Council/Meetings/tcm46.xml April 2011 meeting in Chicago]
 
−
* [http://www.tei-c.org/Activities/Council/Meetings/tcm48.xml November 2011 meeting in Paris]
 
−
* [http://www.tei-c.org/Activities/Council/Meetings/tcm50.xml April 2012 meeting in Ann Arbor]
 
  
−
== Recent practice ==
+
=== "No longer recommended" ===
  
−
=== Soft deprecation ===
+
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:
  
−
"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.
+
* 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.
  
−
Examples:
+
We will not add the "no longer recommended" practice to [[P6-dev]].
  
−
* [http://purl.org/tei/fr/3520653 deprecate <relationGrp>] -- See the resulting [http://www.tei-c.org/release/doc/tei-p5-doc/en/html/ref-relationGrp.html note on definition of relationGrp]
+
=== "Deprecated" ===
−
* [http://purl.org/tei/fr/3266021 dictionary entries with a single <sense>]
 
−
* [http://purl.org/tei/fr/3437509 Use @ref instead of @key]
 
−
* [http://purl.org/tei/fr/3286136 <altIdentifier> is deprecated within <msPart>] -- ''Perhaps this should have been done as a hard deprecation. We didn't specify.''
 
−
* [http://purl.org/tei/fr/3565878 where to put <idno> within <biblStruct>]
 
−
* [http://purl.org/tei/bugs/3590818 Deprecation of "magic token" attributes]
 
  
−
=== Hard deprecation ===
+
According to the [[TEI-Council-FAQ#What_is_the_.22Birnbaum_doctrine.22.3F|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:
  
−
We make adjustments to the prose of the Guidelines, and <code>status="deprecated"</code> is inserted in the Guidelines ODD(s) to mark the deprecated element or attribute.
+
* The appropriate spec is modified to add @validUntil on the appropriate &lt;elementSpec&gt;, &lt;classRef&gt;, or &lt;attDef&gt elements.  The value of @validUntil shall be no sooner than two years from the date of the change.
 +
* 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.
  
−
Examples:
+
After the date specified in @validUntil:
  
−
* [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".
+
* The element or attribute is actually removed from the spec.
−
* [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-quotation.html @form deprecated on <quotation>] -- While the deprecation note appears in red in the element definition, it doesn't appear at all [http://www.tei-c.org/release/doc/tei-p5-doc/en/html/HD.html#HD53 when the element is referenced in the prose of the Guidelines] (Note: deprecation will be noted in the Guidelines when [http://purl.org/TEI/FR/3556778 FR 3556778] is implemented.)
 
−
* [http://purl.org/TEI/FR/3570037 add @unit to <biblScope>, and soft-deprecate @type] -- It said to do "soft, soft deprecation", but use of @status feels like the most clear way to communicate this.  This is one of the many things LB and KH need to resolve in our tcw on deprecation.
 
  
−
== Proposals to clarify practice ==
+
== To do ==
  
−
=== Kevin's ===
+
=== 1. Decide remaining questions ===
  
−
For all deprecations of elements or attributes, we would use <code>status="deprecated"</code> in the appropriate place in the appropriate spec(s) and, where appropriate, add prose to the Guidelines explaining that the practice is no longer recommended.  We would use some sort of mechanism, such as SF tickets, for tracking work that remains to be done in the future.
+
# 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 [http://purl.org/tei/fr/1933481 FR 1933481].
 +
# For deprecations (things we plan to remove), will we:
 +
## list them on a wiki page (this one?)
 +
## [http://purl.org/tei/bug/3435326 create a new tracker item for each]
 +
## announce each on TEI-L
 +
## include them in release notes
  
−
For soft deprecations, we would remove examples in the Guidelines that include an element or attribute in passing but leave any examples that illustrate this element or attribute in particular.  No timeline would be established for removing the element or attribute from the Guidelines.
+
or a combination of these?
  
−
For hard deprecations, we would remove all examples of an element or attribute found in the Guidelines and plan to modify the appropriate spec(s) one year from the time of implementation of the hard deprecation.
+
: I suggest we not create tracker items and simply close [http://purl.org/tei/bug/3435326 bug 3435326].  If Council has already decided to deprecate, we don't need any feedback, and we can use @validUntil to track planned deprecations.  ([[User:Kshawkin|Kshawkin]] 23:10, 18 April 2013 (EDT))
  
−
=== Sebastian's ===
+
=== 2. Modify release building procedure ===
  
−
[W]hen we decide to deprecate something, we move it immediately to the new Deprecated module. One day, we delete it even from there, but for a few years you can still use it if you want, with some extra barrier (making a new schema with that module). ([[User:Rahtz]])
+
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.
  
−
: This is a cunning way of circumventing/subverting the Birnbaum Doctrine. Whereas we used to say "no changes made in the TEI scheme will invalidate your document", we're now saying "no changes made in the TEI
+
=== 3. Add handling of @validUntil to stylesheets for generating Guidelines ===
−
scheme will invalidate your document, so long as you include the "deprecated" module in your schema". Will it work though? Suppose we decide that we want to rename attribute @target to @url  and deprecate @target passim (stranger things have happened). We make the change in P5. We provide alternative definitions for all the elements which used to use @target in which they still do and bung them in the deprecated module. So far so good. But now suppose we make some other change to one or more of those elements, which doesn't involve any deprecation  but which is a straightforward bug fix. Do we apply this fix to the deprecated version as well? What if  (as you suggested earlier) one or more of these elements gets a new attribute ? ([[User:LouBurnard]]/[[User:Lou]])
 
  
−
:: We'd find some mechanism in the deprecated module to work around these issues. Definitely lots of details to work out.  My assumption is that Deprecated would be like a customization we pre-applied before any other customization. So things like element X getting a new attribute is fine, as the module would just be modifying it to add (back) a deleted attribute ([[User:Rahtz]])
+
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!)
  
−
: And I still don't know what we do about "stylistic deprecation" -- where we say this element is permitted in the content model, but you should really  only use it in this particular way (e.g. @target on <locus> ) ([[User:LouBurnard]]/[[User:Lou]])
+
For now leave handling of @status in place in case a release is made before all specs are updated.
  
−
:: Sebastian seemed interested in using Schematron warnings for this.
+
=== 4. Recent "deprecation" practices to be reviewed ===
  
−
::: Sebastian suggested using Schematron to warn when an element is deprecated, but that's probably not so good because it will annoy people still using it. However, we could use Schematron _after_ a deprecated element is finally deleted, to trap for its presence and explain that it was previously deprecated and is now gone. That would only hit people once, when they update their schema after the deletion, and it would provide a helpful explanation for a situation which might otherwise take them by surprise or puzzle them. ([[User:Mholmes]])
+
For all of the following tickets ...
  
−
:: I don't really think this is much of a problem in real life, as long as the Guidelines are chock-full of good examples of what we believe people should be doing. (Of course they're still a bit lacking in that area, but we are committed to fixing that.) Weird uses which are schema-compliant but undesirable tend to arise mainly because there's no useful example for people to follow. The elementSpec for <locus> is good in this respect: there are two examples and a note explaining the issue.
+
* [http://purl.org/tei/fr/3520653 deprecate <relationGrp>]
−
 
+
* [http://purl.org/tei/fr/3266021 dictionary entries with a single <sense>]
−
:: If we give advice and people choose to ignore it, that's up to them, really. We can't police everything. ([[User:Mholmes]])
+
* [http://purl.org/tei/fr/3437509 Use @ref instead of @key]
−
 
+
* [http://purl.org/tei/fr/3286136 <altIdentifier> is deprecated within <msPart>]
−
: I think the value of deprecation is precisely that people can carry on using the deprecated attribute (vel sim) without having to think about it especially, just receiving a gentle warning (in the Guidelines, I guess) rather than that people have to speifically re-introduce a deprecation module to their schema to keep the attribute around. In general people who want to be this proactive with their schemas are the ones who will take account of deprecation the soonest. ([[User:GabrielBoard]]/[[User:Gabriel Bodard]])
+
* [http://purl.org/tei/fr/3565878 where to put <idno> within <biblStruct>]
−
 
+
* [http://purl.org/tei/bugs/3590818 Deprecation of "magic token" attributes]
−
=== Martin's ===
+
* [http://purl.org/tei/bug/3376456 deprecate use of gram except as a child of gramGrp]
−
 
+
* [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).
−
There should be just one type of deprecation. After a set time limit for all deprecations (12 months? 2 years?), we move the feature to a module called "backwardcompatibility" which is not included by default. Perhaps we would use source@mode for this. Notes that we would need to maintain it. For example, in renaming att.sourced to att.edition, a backwardCompatibility module that attempted to restore
+
* [http://www.tei-c.org/release/doc/tei-p5-doc/en/html/ref-quotation.html @form deprecated on <quotation>] (Note: deprecation will be noted in the Guidelines when [http://purl.org/TEI/FR/3556778 FR 3556778] is implemented.)
−
a deleted attribute to att.sourced would fail because it's not there any more.
+
* [http://purl.org/TEI/FR/3570037 add @unit to <biblScope>, and soft-deprecate @type]
−
 
 
−
: Yes, it would take some careful thought on how to do it. But it seems worth a try, a maintained schema which confirmed Birnbaumites could access. ([[User:Rahtz]])
 
−
 
 
−
:: I think that's just silly. How would this be different from (or more useful than) a previous version of the schema in which the various deprecations had not yet taken effect? I say when things are removed, they are removed. End of. ([[User:LouBurnard]]/[[User:Lou]])
 
−
 
 
−
::: Because the schema would also include new things. the scenario Is that I need t keep using @targets cos my tool supports that, and I can't afford to change. I have my loads of docs using that markup. But I also want to use the new @magic markup. ([[User:Rahtz]])
 
−
 
 
−
::: It enables you to take advantage of new additions and changes to the schema, without having to abandon your beloved @key (or whatever it is). ([[User:Mholmes]])
 
−
 
 
−
:::: But chances are my old tool won't be able to do anything with the new @magic so why would I bother? Or if I want to make it do so, then I might as well teach it not to use old @targets. ([[User:LouBurnard]]/[[User:Lou]])
 
−
 
 
−
While tei_all would not include backwardCompatibility, we could provide an additional customization that does include it.
 
−
 
 
−
: FWIW, I think a "backwards compatibility" module would be over-engineering. If people want to recover something we've removed, åthere are other and simpler ways of doing so. ([[User:LouBurnard]]/[[User:Lou]])
 
−
 
 
−
=== Gabby's ===
 
−
 
 
−
I vote for the red "Deprecated" flag in the element/class Spec page.
 
  
−
=== James's ===
+
... we need to make sure they've been handled according to the above policy.
  
−
Marked as deprecated on the reference page preferably with a note with date or similar at which it will be removed, a schematron warning rule set up, and the <desc> changed to be prefixed with 'DEPRECATED: '.  (Changing the <desc> will result in people noticing this in tooltips in software like oXygen, make it that much more evident on the reference page, and where specDesc has been used to pull in the description elsewhere.) ([[User:JamesC]])
+
KH will do the following:
  
−
=== (fill in yours here) ===
+
* 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 &lt;remarks&gt;.
 +
* For deprecations, reopen the ticket if necessary and assign to SB with a note to add a Schematron warning.
  
−
== To be resolved ==
+
SB will do the following:
  
−
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.
+
* Add a Schematron warning for the "no longer recommended" practices.
  
−
* [http://purl.org/tei/bug/3435326 We might change our practice to create a new type of tracker item instead of using a category].
+
=== 5. Remove @status='deprecated' in stylesheets ===
−
* 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?
 
  
−
Also, should we adopt any of the practices [[Talk:Deprecation|suggested on the talk page]]?
+
SR will change the stylesheets to remove display of "(deprecated)" for @status='deprecated' since this is no longer needed.
  
 
[[Category:Council]]
 
[[Category:Council]]

Revision as of 05:10, 19 April 2013

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.

We will not add the "no longer recommended" practice to P6-dev.

"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&gt elements. The value of @validUntil shall be no sooner than two years from the date of the change.
  • 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

  1. 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.
  2. For deprecations (things we plan to remove), will we:
    1. list them on a wiki page (this one?)
    2. create a new tracker item for each
    3. announce each on TEI-L
    4. include them in release notes

or a combination of these?

I suggest we not create tracker items and 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))

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

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

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.

4. Recent "deprecation" practices to be reviewed

For all of the following tickets ...

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

5. Remove @status='deprecated' in stylesheets

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

Retrieved from "https://wiki.tei-c.org/index.php?title=Practices_no_longer_recommended_or_now_deprecated&oldid=11879"