css should define and use consistent terminology for words like "deprecated", "obsolete"

[frivoal]

(moved from #4087 (comment), which was a discussion about one particular usage of such terminology)

Discussed this offline with @sideshowbarker (a while back, only remembering it now): css should define and use consistent terminology for words like "deprecated", "obsolete", and other similar terms.

Here are some of the possible meanings for such words (non exhaustive list):

1. Using this is a bad idea (but if you do, here's how it works)
2. this is an old bad name/API for a useful thing which has a new good name/API. Use the new one if you can, be mindful of compat.
3. This is going away, don't count on it being there, or on continuing to do anything

I think, at present, CSS specs have some cases of 1 (https://drafts.csswg.org/mediaqueries-4/#mf-deprecated), some cases of 2 (https://drafts.csswg.org/css-text-3/#valdef-word-break-break-word. I can't quite tell if https://www.w3.org/TR/css-color-3/#css2-system is 1 or 3. We call all these "deprecated".

Should we clean up our terminology to account for this nuance? Is there some systematic (and formally defined) existing use of these words by other groups we could align to?

Note that this is about individual features, and is different from obsoleting / superseding / rescinding entire specifications. That's clearly defined in the Process.

[svgeesus]

I can't quite tell if https://www.w3.org/TR/css-color-3/#css2-system is 1 or 3.

It is mostly 1. It isn't really 3 because they went away then half of them came back which is kind of an antipattern.

And then we have named colors aka X11 colors which are

1a. Using this is a bad idea (but if you do, here's how it works) and while we can't get rid of them we also won't add any more so please stop asking; nor can we rename them or change what they mean.

(related to Change three color names and new predefined colors)

[svgeesus]

In several fields, deprecation is the discouragement of use of some terminology, feature, design, or practice, typically because it has been superseded or is no longer considered efficient or safe, without completely removing it or prohibiting its use. Typically, deprecated materials are not completely removed to ensure legacy compatibility or back up practice in case new methods are not functional in an odd scenario.
https://en.wikipedia.org/wiki/Deprecation

seems like an okay definition

[fantasai]

IIRC in other fields, #3 is possible, and stuff moves from deprecation in one version to obsoletion in another, but on the Web, we generally can't remove things so #3 hasn't really been an option.

I think the Wikipedia definition @svgeesus cites is a pretty good one. I don't think we need to define terms which follow their normal English usage?

As for obsoletion, we generally pair it with "optional to implement" in RFC2119 terms, so I think there's nothing to specially define there, either.

[sideshowbarker]

Is there some systematic (and formally defined) existing use of these words by other groups we could align to?

The HTML spec never uses the word deprecated at all; instead it only uses obsolete — but further makes a distinction between A) obsolete features that are obsolete but conforming — which is what most other specs label typically use deprecated for — and B) obsolete features that are completely non-conforming.

See https://html.spec.whatwg.org/multipage/obsolete.html#obsolete

The reason the HTML spec uses obsolete rather than deprecated is that it wouldn’t make any sense to label those case B completely non-conforming features as “deprecated”.

So in the HTML-spec taxonomy, I think all three cases listed in the issue description map to “obsolete but conforming”.

And given that, I think what the issue description focuses on is basically what most other specs would call “deprecated”.

The HTML-spec taxonomy is arguably idiosyncratic and not aligned super well with what most other specs do.

That said, I think the HTML-spec taxonomy does expose that there’s at least one more case to consider, which is this:

4. This feature/name is in no way currently specified anywhere — and it’s either gone from implementations already, or else if if it’s still in implementations, you should have zero expectation that it works interoperably. Don’t use it.

That #4 case is what the HTML case calls non-conforming.

But I think most other specs don’t even list such completely non-conforming features at all.

Given all that, as far as just the question of how to distinguish deprecated vs obsolete, I would suggest not to use both but instead only use one or the other. And between the two, I think deprecated is the one that’s more-commonly used by most specs, and the one that’s somewhat less ambiguous.

However, if as the HTML spec does, you also want to include consideration of case #4 — features that are completely non-conforming — then it seems necessary to use the word obsolete rather than deprecated; it otherwise wouldn’t make much sense to describe any features as “deprecated and non-conforming” (whereas it does make sense to describe such features a “obsolete and non-conforming”).

[fantasai]

The CSS specs use 'deprecated' and 'obsoleted' as value judgements. What's required for conformance or not is a separate question represented via RFC2119 terminology. I believe our usage of 'deprecated' and 'obsolete' matches English usage, so I don't think there's anything to do here, unless there exists some specific feature that needs to be relabeled?

[sideshowbarker]

What's required for conformance or not is a separate question represented via RFC2119 terminology.

At https://html.spec.whatwg.org/multipage/introduction.html#conformance-requirements-for-authors the HTML spec explains how it defines conformance requirements for authors and documents as a conformance class, and explains that the spec defines conformance requirements for distinguishing between a conforming document and non-conforming document.

And the HTML spec uses RFC2119 terminology to specify those document/authoring conformance requirements.

In particular, the HTML spec defines some document/authoring conformance requirements as cases that MUST NOT be used by documents/authors, and some others as cases that instead SHOULD NOT be used by documents/authors.

For the set of CSS specs, is there somewhere a similar explanation of whether CSS defines requirements for documents/authors as a conformance class?

If a CSS spec states that a particular feature is deprecated, does that mean authors MUST NOT use that feature, or does it mean that authors SHOULD NOT use that feature? Does a CSS feature marked as obsolete mean that authors MUST NOT use that feature, or does it mean that authors SHOULD NOT use that feature?

It seems like CSS specs do actually intend to define conformance requirements for documents/authors. And therefore it seems useful for there to be an explanation somewhere among the set of specs — similar to what the HTML spec has — that explicitly addresses document/authoring conformance requirements.

And along with that, if the terms deprecated and obsolete are intended to have some effect on what documents/authors must not do or should not do, then it seems like the intended effect of those terms for documents/authors should be explicitly and unambiguously stated somewhere.

As a maintainer of conformance-checking tools, I have a very practical need for those terms to be unambiguously defined — and in general, for the CSS specs to be unambiguous about identifying things that documents/authors MUST NOT have, and identifying things that documents/authors SHOULD NOT have, and unambiguously distinguishing between the two.

In practical terms, what the distinction means for me and other developers of conformance-checking tools is that if a CSS spec defines a case as a MUST NOT, then we make our conformance-checkers report an error for any instance of that — and for SHOULD NOT cases, we instead report just a warning.

So as a conformance-checker developer, ultimately what I want for any case of the terms deprecated and obsolete in a CSS spec is to clearly know: Do I make my conformance checker report an error for that case? Or do I make it report a warning?

And I’d like to be able to trust that the set of CSS specs are using those terms consistently, based on precise meanings defined somewhere, and with some formal statement somewhere in the set of CSS specs that explains how I can tell the difference between a case that a CSS spec intends MUST NOT be used by documents/authors versus a case that a CSS spec instead intends SHOULD NOT be used by documents/authors.

[css-meeting-bot]

The CSS Working Group just discussed css should define and use consistent terminology for words like "deprecated", "obsolete", and agreed to the following:

• RESOLVED: Close no change but open issues on spec areas where it's not clear what the intent was for a deprecation

The full IRC log of that discussion

<dael> Topic: css should define and use consistent terminology for words like "deprecated", "obsolete"
<dael> github: https://github.com//issues/5644
<dael> florian: Raised a while back by MIke Smith indirectly b/c he was confused. Used deprecated in a few places and the meaning has changed over time. Should we use deprecated for all the meaning or do we be more specific
<dael> florian: COuld be using this feature is bad idea but we have it or this feature is old bad name but we're documenting it. Or we're documenting it but browsers are removing it. Or in HTML we're not spec this feature but we're telling you it used to exist.
<dael> florian: The first two are the ones we use. Maybe that's fine. Maybe we should pick it to mean one.
<dael> florian: No strong opinions on which way, but this is the question
<dael> florian: Reason Mike Smith reacted is we documented as deprecated something with an old name but he thought we meant this is old do not use. THat's where potential need to distinguish came from
<dael> fantasai: WE use in English meaning to express disapproval. If an impl required to have it separately documented. Either must impl or should impl. We're clear. If we dissourage users that's separate term. Deprecated is basically a value judgement and an indication of preference from WG
<dael> fantasai: I think we're clear on what's required and what's discouraged.
<dael> florian: As long as we keep being explicit for deprecated feature nomrative requirements we're good.
<fantasai> s/to have it/to have it, it's/
<dael> florian: I'm fine closing no change, but it was raised
<fantasai> s/documented/documented via RFC2119 terminology/
<dael> smfr: I think it's important to distinguish rec for author and instructions for impl. Maybe something being obsolete should only be things in spec and deprecation is for UAs.
<dael> florian: WE do distunguish but we do with explicit text, not keywords
<tantek> should we escalate to the TAG to provide a more precise definition of "deprecate(d)" and "obsolete(d)" for consistent use across W3C specs?
<dael> fantasai: We say UA must or should and users should or should not. I don't think we use it in the place of must or should. Maybe some image angles will become obsolete. Otheriwse we use deprecated where we prefer people didn't use it but you might have to in certain contexts because it's out there
<dael> smfr: A clear distinction between browsers might have to impl and authors might have to use is useful
<tantek> q?
<dael> florian: We absolutely should. But do we do it through termonology or through text?
<dael> fantasai: We say it's deprecated and you have to impl or and you shouldn't impl. THe conformace requirements is expressed with RFC2119
<tantek> should we stop using those terms then?
<dael> smfr: I think better explained with examples
<dael> astearns: WE do most often add text describing our intent. In cases where it's not clear we can open issues to make that better. But not come up with specific spec terms
<dael> astearns: I think I would rather not a sepcific term b/c sometimes people don't follow links for meaning so it could hide things that are in prose
<dael> astearns: Prop: Close no change but open issues on spec areas where it's not clear what the intent was for a deprecation
<dael> tantek: [missed]
<tantek> tantek: should we discourage future use of those terms?
<dael> fantasai: When we same something must be impl but authors shouldn't use...must be impl like system colors but this is a bad idea so it shoudln't be in your css vocab
<dael> tantek: should we discourage editors from using deprecated or obsoleted?
<dael> fantasai: I don't think so. They have useful meanings in English
<dael> astearns: They're useful terms we're just not loading them with anything becides standard english meaning
<dael> astearns: Objections?
<dael> RESOLVED: Close no change but open issues on spec areas where it's not clear what the intent was for a deprecation