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

From TEIWiki
Jump to navigation Jump to search
(→‎Sebastian's: Martin's note to tei-council on 2013-01-17, plus a typo fix)
(→‎5. Recent "deprecations" to be reviewed: link to https://sourceforge.net/p/tei/feature-requests/486/ (for solving the three unresolved tickets))
 
(27 intermediate revisions by 2 users not shown)
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]
+
http://www.tei-c.org/Activities/Council/Working/tcw27.xml
−
* [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 ==
+
== To do ==
  
−
=== Soft deprecation ===
+
=== 1. Decide remaining questions ===
  
−
"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.
+
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 [http://purl.org/tei/fr/1933481 FR 1933481].
  
−
Examples:
+
: 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. ([[User:Kshawkin|Kshawkin]] 17:09, 16 May 2013 (EDT))
  
−
* [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]
+
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?
−
* [http://purl.org/tei/fr/3266021 dictionary entries with a single <sense>]
+
# list them on a wiki page (this one?)
−
* [http://purl.org/tei/fr/3437509 Use @ref instead of @key]
+
# [http://purl.org/tei/bug/3435326 create a new tracker item for each]
−
* [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.''
+
# announce each on TEI-L
−
* [http://purl.org/tei/fr/3565878 where to put <idno> within <biblStruct>]
 
  
−
=== Hard deprecation ===
+
: I suggest we not create tracker items and therefore 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))
  
−
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.
+
: 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. ([[User:Mholmes|Mholmes]])
  
−
Examples:
+
=== 2. Create a new tcw with the policy, plus answers to the remaining questions, for future reference ===
  
−
* [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".
+
Once Council reviews that the intent from the Providence meeting has been correctly represented, KH will create this document (as originally requested in Oxford).
−
* [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 ==
+
: [http://www.tei-c.org/Activities/Council/Working/tcw27.xml TCW27] was created on 16 May 2013. ([[User:Kshawkin|Kshawkin]] 15:46, 16 June 2013 (EDT))
  
−
=== Kevin's ===
+
=== 3. Modify release building procedure ===
  
−
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.
+
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.
  
−
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.
+
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.
  
−
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 see that SR's suggestion has already been implemented! ([[User:Kshawkin|Kshawkin]] 00:54, 20 June 2013 (EDT))
  
−
=== Sebastian's ===
+
=== 4. Add handling of @validUntil to stylesheets for generating Guidelines ===
  
−
[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]])
+
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!)
  
−
: 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
+
For now leave handling of @status in place in case a release is made before all specs are updated.
−
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]])
+
=== 5. Recent "deprecations" to be reviewed ===
  
−
: 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 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.
  
−
:: Sebastian seemed interested in using Schematron warnings for this.
+
{| class="wikitable"
 +
|-
 +
! recent "deprecation"
 +
! if interpreted according to TCW27
 +
|-
 +
| [http://purl.org/tei/fr/3520653 deprecate <relationGrp>]
 +
| deprecated on 2012-06-17
 +
|-
 +
| [http://purl.org/tei/fr/3266021 dictionary entries with a single <sense>]
 +
| no longer recommended
 +
|-
 +
| [http://purl.org/tei/fr/3437509 Use @ref instead of @key]
 +
| no longer recommended
 +
|-
 +
| [http://purl.org/tei/fr/3286136 <altIdentifier> is deprecated within <msPart>]
 +
| deprecated on 2011-04-24
 +
|-
 +
| [http://purl.org/tei/fr/3565878 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.)
 +
|-
 +
| [http://purl.org/tei/bugs/3590818 Deprecation of "magic token" attributes]
 +
| (still open)
 +
|-
 +
| [http://purl.org/tei/bug/3376456 deprecate use of gram except as a child of gramGrp]
 +
| deprecated on 2011-12-05
 +
|-
 +
| [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], [http://tei.svn.sourceforge.net/viewvc/tei/trunk/P5/Source/Specs/alt.xml?r1=8763&r2=8807 8807], 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).
 +
| deprecated on 2011-03-20
 +
|-
 +
| [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.)
 +
| deprecated on 2012-04-28 (Don't see how the other ticket relates!)
 +
|-
 +
| [http://purl.org/TEI/FR/3570037 add @unit to <biblScope>, and soft-deprecate @type]
 +
| deprecated on 2012-12-17
 +
|}
  
−
::: 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]])
+
Then KH will do the following:
  
−
:: 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.
+
* 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.
  
−
:: If we give advice and people choose to ignore it, that's up to them, really. We can't police everything. ([[User:Mholmes]])
+
At [http://sourceforge.net/p/tei/code/12284/ revision 12284] and [http://sourceforge.net/p/tei/code/12285/ revision 12285], KH has:
  
−
: 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]])
+
* 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>
  
−
=== Martin's ===
+
In addition, I have added notes to [https://sourceforge.net/p/tei/feature-requests/459/ ticket #459] about places where Schematron warnings are needed (instead of reopening tickets as originally planned).
  
−
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
+
SB will do the following:
−
a deleted attribute to att.sourced would fail because it's not there any more.
 
  
−
: 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]])
+
* Add a Schematron warning for the "no longer recommended" practices.  See [https://sourceforge.net/p/tei/feature-requests/459/ #459 warn user of dropped constructs].
 +
* Figure out how to solve the three tickets above that Kevin couldn't solve. See [https://sourceforge.net/p/tei/feature-requests/486/ #486 deprecating members of a content model].
  
−
:: 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]])
+
=== 6. Remove @status='deprecated' in stylesheets  ===
  
−
::: 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]])
+
SR will change the stylesheets to remove display of "(deprecated)" for @status='deprecated' since this is no longer needed.
  
−
::: 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]])
+
: I've created https://sourceforge.net/p/tei/feature-requests/463/ and assigned to SR. ([[User:Kshawkin|Kshawkin]] 23:03, 20 June 2013 (EDT))
−
 
 
−
:::: 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 ===
 
−
 
 
−
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]])
 
−
 
 
−
=== (fill in yours here) ===
 
−
 
 
−
== To be resolved ==
 
−
 
 
−
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.
 
−
 
 
−
* [http://purl.org/tei/bug/3435326 We might change our practice to create a new type of tracker item instead of using a category].
 
−
* 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]]?
 
  
 
[[Category:Council]]
 
[[Category:Council]]

Latest revision as of 01:31, 9 December 2013

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:

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:

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))
Retrieved from "https://wiki.tei-c.org/index.php?title=Practices_no_longer_recommended_or_now_deprecated&oldid=12750"