Talk:Practices no longer recommended or now deprecated - Revision history

Kshawkin: moved Talk:Deprecation to Talk:Practices no longer recommended or now deprecated: The former "soft" and "hard" deprecation are now "no longer recommended" and "deprecated".

2013-04-19T03:12:18Z

moved Talk:Deprecation to Talk:Practices no longer recommended or now deprecated: The former "soft" and "hard" deprecation are now "no longer recommended" and "deprecated".

← Older revision	Revision as of 03:12, 19 April 2013
(No difference)

Kshawkin: clearing this since it no longer applies to text on main page

2013-04-19T03:11:00Z

clearing this since it no longer applies to text on main page

← Older revision		Revision as of 03:11, 19 April 2013
Line 1:		Line 1:
	This is very helpful. The first thing that occurs to me is that the "soft deprecation" method is hard to notice in the Guidelines; the Note in which it's mentioned in e.g. <relationGrp> is right at the bottom of the page:

	~~<http://www.tei-c.org/release/doc/tei-p5-doc/en/html/ref-relationGrp.html>~~

	and many people would use the tag unknowingly without getting that far. The fact that <relationGrp> is no longer mentioned in the chapter linked from the element page is perhaps a clue, but not a very good one. We could make the deprecation more evident by putting some signal directly into the first row/cell of the element page (such as the red text shown in the hard-deprecated @targets definition).

	Personally, I don't like the distinction between hard and soft deprecation. What "soft" really means in the case of e.g. relationGrp is that the element is retained for backwards-compatibility; I think that should always be temporary, albeit perhaps long-lasting, and the end-result of deprecation should be eventual removal/replacement. ([[User:Mholmes]])

	: I agree that we should always use <code>status="deprecated"</code> in the ODD for any type of deprecation for exactly the reason Martin mentions. It seems that the difference between "hard" and "soft" is just a question of how long we intend to leave the deprecated practice in the TEI Guidelines. ([[User:Kshawkin\|Kshawkin]] 19:22, 20 December 2012 (EST)) In fact, an example of someone not noticing a deprecation note at the bottom of a document is [http://listserv.brown.edu/archives/cgi-bin/wa?A2=ind1212&L=TEI-L&D=0&P=88213 here on TEI-L]. ([[User:Kshawkin\|Kshawkin]] 14:05, 23 December 2012 (EST))


	~~Let me try at least to state the workflow I would have in mind for the use of tickets for deprecation:~~
	* when the council decides to deprecate "something", a ticket with status="deprecated" is created that describes the actual deprecation thing. This ticket also states a deprecation period (or open until the council decides the "thing" should definitely disappear)
	* closing the ticket means that the deprecation period is over, namely that the element, attribute, feature etc. has been removed from the guideline

	~~The ticket has thus a multiple role:~~
	* it documents the deprecation (thus making it easy to publicize (in particular on the TEI website)), as a sort of reified warning
	* it allows the community to react to the ticket ("no, stop! I have a zillion documents using this")
	* trace back decisions/reasons for changes

	~~In no way, IMHO, "old" tickets should be changed to status="deprecated" , but a new one should be made, which in turn may point to the initial discussion(s) that lead to its creation.~~

	~~And this for both soft and hard, I would say. ([[User:Romary]])~~


	I've always viewed soft deprecation as an entirely unofficial form of deprecation. I.e. we're not yet stating that this is deprecated, we're just trying to remove active recommendations for its use. (i.e. making sure our examples use @ref instead of @key)

	I believe that what Laurent recommends [. . .] is the deprecation procedure we agreed to previously. That when we decide to really really deprecate something, that we not only add a @status="deprecated" to it, remarks noting that it is deprecated, but open a ticket with the deprecated category on sf as a place to document and have discussion concerning it post-deprecation. That ticket should contain a date by which the object should be removed from the guidelines.

	~~An example of where we've partly done this is @targets on alt/join/link but I've no recollection if we created a ticket concerning it? ([[User:James]])~~

	: As Martin notes abovce, the problem with only including <code>status="deprecated"</code> on hard deprecations is that people are unlikely to notice that we are no longer promoting the practice. I see no value in not explicitly labeling something as deprecated but only removing active recommendations for its use. ([[User:Kshawkin\|Kshawkin]] 19:22, 20 December 2012 (EST))

	A quick grep through the guidelines shows us "deprecating" several different kinds of thing. Most of the time it's a specific attribute or (less often) an element, which we retain for purposes of backwards compatibility but for which we now recognise a better solution. Flagging those up with @status=deprecated and in due course removing them is not difficult. But we also tend to talk about "deprecated" usages -- for example, that a dictionary entry with only one sense need not tag that sense explicitly; or that <ref> should not be used within <biblScope>; or that <list> should not used within <keywords>. Such things could (and surely should) be caught by additional schematron constraints: but there are cases for which I don't think any automated method will be feasible: for example the recommendation against using @target (rather than @facs) on <locus> to point to an image, or against using <c> rather than <pc> to mark punctuation marks. ([[User:LouBurnard]]/[[User:Lou]])

Kshawkin: wiki markup

2013-01-18T02:45:10Z

wiki markup

← Older revision		Revision as of 02:45, 18 January 2013
Line 32:		Line 32:
	: As Martin notes abovce, the problem with only including <code>status="deprecated"</code> on hard deprecations is that people are unlikely to notice that we are no longer promoting the practice. I see no value in not explicitly labeling something as deprecated but only removing active recommendations for its use. ([[User:Kshawkin\|Kshawkin]] 19:22, 20 December 2012 (EST))		: As Martin notes abovce, the problem with only including <code>status="deprecated"</code> on hard deprecations is that people are unlikely to notice that we are no longer promoting the practice. I see no value in not explicitly labeling something as deprecated but only removing active recommendations for its use. ([[User:Kshawkin\|Kshawkin]] 19:22, 20 December 2012 (EST))

	A quick grep through the guidelines shows us "deprecating" several different kinds of thing. Most of the time it's a specific attribute or (less often) an element, which we retain for purposes of backwards compatibility but for which we now recognise a better solution. Flagging those up with @status=deprecated and in due course removing them is not difficult. But we also tend to talk about "deprecated" usages -- for example, that a dictionary entry with only one sense need not tag that sense explicitly; or that <ref> should not be used within <biblScope>; or that <list> should not used within <keywords>. Such things could (and surely should) be caught by additional schematron constraints: but there are cases for which I don't think any automated method will be feasible: for example the recommendation against using @target (rather than @facs) on <locus> to point to an image, or against using <c> rather than <pc> to mark punctuation marks. ([[User:LouBurnard]]/[[User:Lou]])		A quick grep through the guidelines shows us "deprecating" several different kinds of thing. Most of the time it's a specific attribute or (less often) an element, which we retain for purposes of backwards compatibility but for which we now recognise a better solution. Flagging those up with @status=deprecated and in due course removing them is not difficult. But we also tend to talk about "deprecated" usages -- for example, that a dictionary entry with only one sense need not tag that sense explicitly; or that <ref> should not be used within <biblScope>; or that <list> should not used within <keywords>. Such things could (and surely should) be caught by additional schematron constraints: but there are cases for which I don't think any automated method will be feasible: for example the recommendation against using @target (rather than @facs) on <locus> to point to an image, or against using <c> rather than <pc> to mark punctuation marks. ([[User:LouBurnard]]/[[User:Lou]])

Kshawkin: new note from Lou about various types of deprecation

2013-01-18T02:44:08Z

new note from Lou about various types of deprecation

← Older revision		Revision as of 02:44, 18 January 2013
Line 31:		Line 31:

	: As Martin notes abovce, the problem with only including <code>status="deprecated"</code> on hard deprecations is that people are unlikely to notice that we are no longer promoting the practice. I see no value in not explicitly labeling something as deprecated but only removing active recommendations for its use. ([[User:Kshawkin\|Kshawkin]] 19:22, 20 December 2012 (EST))		: As Martin notes abovce, the problem with only including <code>status="deprecated"</code> on hard deprecations is that people are unlikely to notice that we are no longer promoting the practice. I see no value in not explicitly labeling something as deprecated but only removing active recommendations for its use. ([[User:Kshawkin\|Kshawkin]] 19:22, 20 December 2012 (EST))

			A quick grep through the guidelines shows us "deprecating" several different kinds of thing. Most of the time it's a specific attribute or (less often) an element, which we retain for purposes of backwards compatibility but for which we now recognise a better solution. Flagging those up with @status=deprecated and in due course removing them is not difficult. But we also tend to talk about "deprecated" usages -- for example, that a dictionary entry with only one sense need not tag that sense explicitly; or that <ref> should not be used within <biblScope>; or that <list> should not used within <keywords>. Such things could (and surely should) be caught by additional schematron constraints: but there are cases for which I don't think any automated method will be feasible: for example the recommendation against using @target (rather than @facs) on <locus> to point to an image, or against using <c> rather than <pc> to mark punctuation marks. ([[User:LouBurnard]]/[[User:Lou]])

Mholmes: Typo fixes

2013-01-14T16:13:58Z

Typo fixes

← Older revision		Revision as of 16:13, 14 January 2013
Line 12:		Line 12:
	Let me try at least to state the workflow I would have in mind for the use of tickets for deprecation:		Let me try at least to state the workflow I would have in mind for the use of tickets for deprecation:
	* when the council decides to deprecate "something", a ticket with status="deprecated" is created that describes the actual deprecation thing. This ticket also states a deprecation period (or open until the council decides the "thing" should definitely disappear)		* when the council decides to deprecate "something", a ticket with status="deprecated" is created that describes the actual deprecation thing. This ticket also states a deprecation period (or open until the council decides the "thing" should definitely disappear)
	* closing the ticket means that the deprecation period is over, namely that the element, attribute,feature etc. has been removed from the guideline		* closing the ticket means that the deprecation period is over, namely that the element, attribute, feature etc. has been removed from the guideline

	The ticket has thus a multiple ~~roe~~:		The ticket has thus a multiple role:
	* it documents the deprecation (thus making it easy to publicize (in particular on the TEI website)), as a sort of reified warning		* it documents the deprecation (thus making it easy to publicize (in particular on the TEI website)), as a sort of reified warning
	* it allows the community to react to the ticket ("no, stop! I have a zillion documents using this")		* it allows the community to react to the ticket ("no, stop! I have a zillion documents using this")

Kshawkin: link to TEI-L where someone didn't notice a deprecation note

2012-12-23T19:05:34Z

link to TEI-L where someone didn't notice a deprecation note

← Older revision		Revision as of 19:05, 23 December 2012
Line 7:		Line 7:
	Personally, I don't like the distinction between hard and soft deprecation. What "soft" really means in the case of e.g. relationGrp is that the element is retained for backwards-compatibility; I think that should always be temporary, albeit perhaps long-lasting, and the end-result of deprecation should be eventual removal/replacement. ([[User:Mholmes]])		Personally, I don't like the distinction between hard and soft deprecation. What "soft" really means in the case of e.g. relationGrp is that the element is retained for backwards-compatibility; I think that should always be temporary, albeit perhaps long-lasting, and the end-result of deprecation should be eventual removal/replacement. ([[User:Mholmes]])

	: I agree that we should always use <code>status="deprecated"</code> in the ODD for any type of deprecation for exactly the reason Martin mentions. It seems that the difference between "hard" and "soft" is just a question of how long we intend to leave the deprecated practice in the TEI Guidelines. ([[User:Kshawkin\|Kshawkin]] 19:22, 20 December 2012 (EST))		: I agree that we should always use <code>status="deprecated"</code> in the ODD for any type of deprecation for exactly the reason Martin mentions. It seems that the difference between "hard" and "soft" is just a question of how long we intend to leave the deprecated practice in the TEI Guidelines. ([[User:Kshawkin\|Kshawkin]] 19:22, 20 December 2012 (EST)) In fact, an example of someone not noticing a deprecation note at the bottom of a document is [http://listserv.brown.edu/archives/cgi-bin/wa?A2=ind1212&L=TEI-L&D=0&P=88213 here on TEI-L]. ([[User:Kshawkin\|Kshawkin]] 14:05, 23 December 2012 (EST))

Kshawkin: responses to some comments

2012-12-21T00:22:40Z

responses to some comments

← Older revision		Revision as of 00:22, 21 December 2012
Line 6:		Line 6:

	Personally, I don't like the distinction between hard and soft deprecation. What "soft" really means in the case of e.g. relationGrp is that the element is retained for backwards-compatibility; I think that should always be temporary, albeit perhaps long-lasting, and the end-result of deprecation should be eventual removal/replacement. ([[User:Mholmes]])		Personally, I don't like the distinction between hard and soft deprecation. What "soft" really means in the case of e.g. relationGrp is that the element is retained for backwards-compatibility; I think that should always be temporary, albeit perhaps long-lasting, and the end-result of deprecation should be eventual removal/replacement. ([[User:Mholmes]])

			: I agree that we should always use <code>status="deprecated"</code> in the ODD for any type of deprecation for exactly the reason Martin mentions. It seems that the difference between "hard" and "soft" is just a question of how long we intend to leave the deprecated practice in the TEI Guidelines. ([[User:Kshawkin\|Kshawkin]] 19:22, 20 December 2012 (EST))


Line 27:		Line 29:

	An example of where we've partly done this is @targets on alt/join/link but I've no recollection if we created a ticket concerning it? ([[User:James]])		An example of where we've partly done this is @targets on alt/join/link but I've no recollection if we created a ticket concerning it? ([[User:James]])

			: As Martin notes abovce, the problem with only including <code>status="deprecated"</code> on hard deprecations is that people are unlikely to notice that we are no longer promoting the practice. I see no value in not explicitly labeling something as deprecated but only removing active recommendations for its use. ([[User:Kshawkin\|Kshawkin]] 19:22, 20 December 2012 (EST))

Kshawkin: copied in stuff from tei-council discussion

2012-08-12T14:43:48Z

copied in stuff from tei-council discussion

New page

This is very helpful. The first thing that occurs to me is that the "soft deprecation" method is hard to notice in the Guidelines; the Note in which it's mentioned in e.g. <relationGrp> is right at the bottom of the page:

<http://www.tei-c.org/release/doc/tei-p5-doc/en/html/ref-relationGrp.html>

and many people would use the tag unknowingly without getting that far. The fact that <relationGrp> is no longer mentioned in the chapter linked from the element page is perhaps a clue, but not a very good one. We could make the deprecation more evident by putting some signal directly into the first row/cell of the element page (such as the red text shown in the hard-deprecated @targets definition).

Personally, I don't like the distinction between hard and soft deprecation. What "soft" really means in the case of e.g. relationGrp is that the element is retained for backwards-compatibility; I think that should always be temporary, albeit perhaps long-lasting, and the end-result of deprecation should be eventual removal/replacement. ([[User:Mholmes]])

Let me try at least to state the workflow I would have in mind for the use of tickets for deprecation:
* when the council decides to deprecate "something", a ticket with status="deprecated" is created that describes the actual deprecation thing. This ticket also states a deprecation period (or open until the council decides the "thing" should definitely disappear)
* closing the ticket means that the deprecation period is over, namely that the element, attribute,feature etc. has been removed from the guideline

The ticket has thus a multiple roe:
* it documents the deprecation (thus making it easy to publicize (in particular on the TEI website)), as a sort of reified warning
* it allows the community to react to the ticket ("no, stop! I have a zillion documents using this")
* trace back decisions/reasons for changes

In no way, IMHO, "old" tickets should be changed to status="deprecated" , but a new one should be made, which in turn may point to the initial discussion(s) that lead to its creation.

And this for both soft and hard, I would say. ([[User:Romary]])

I've always viewed soft deprecation as an entirely unofficial form of deprecation. I.e. we're not yet stating that this is deprecated, we're just trying to remove active recommendations for its use. (i.e. making sure our examples use @ref instead of @key)

I believe that what Laurent recommends [. . .] is the deprecation procedure we agreed to previously. That when we decide to really really deprecate something, that we not only add a @status="deprecated" to it, remarks noting that it is deprecated, but open a ticket with the deprecated category on sf as a place to document and have discussion concerning it post-deprecation. That ticket should contain a date by which the object should be removed from the guidelines.

An example of where we've partly done this is @targets on alt/join/link but I've no recollection if we created a ticket concerning it? ([[User:James]])