Record discouraged status (e.g., obsolete, deprecated, legacy, etc.)

[ddbeck]

Some features may end up with a discouraging notice for web developers. For example:

• An existing feature can be deprecated by a browser (whether or not they'll soon remove it), by issuing in-browser warnings or authoritative documentation
• An existing feature can be marked as a kind of anti-feature by a specification, through a formal mechanism (e.g., HTML's Obsolete but conforming features) or one-off advisories (e.g., the "Authors should not use unicode-bidi in HTML documents" note in the CSS Writing Modes Level 3 spec).
• Proposed features can be withdrawn (with implementations expected to be withdrawn soon after)

An example of such a case is shown with #310.

We ought to be able to record evidence of such discouraging information. We'll probably need a field (discouraged?) that accepts one or more URLs.

[atopal]

That sounds good to me.

[ddbeck]

On yesterday's WebDX call, we talked about this. Some highlights:

Why don't we cover deprecated features today?

We did not include deprecated features in the definition of Baseline because knew it was fraught. It's potentially confusing to developers to tell them that a feature is Baseline if we also know that specs or vendors are saying things to discourage using that feature. We kicked the can down the road.

Urgency of the problem

That can can't really be kicked again. We're now to the point that we cannot completely describe the platform without somehow handling deprecated features. And we'll soon have covered the non-deprecated parts of the platform.

Distinguishing kinds of deprecations

There's really two kinds of deprecated features and we ought to be able to distinguish them:

• Features that are discouraged, but will remain with the platform indefinitely (with support at varying levels). This is the larger fraction.
• Features that are being actively removed from browsers. This is a small, but higher consequence fraction.

The latter case, pending removals, is partly related to #955. Right now, we can't communicate any likely future conditions for features (e.g., landing in a browser soon or Baseline soon) despite the availability of data that could make it possible. This also extends to active removals (e.g., we don't but could set a status showing that feature is about to be removed).

How do we know if something is deprecated or on the road to removal?

There were a few questions about how we know something is deprecated. Mostly that comes from BCD, following these guidelines. I also linked to an article I wrote around the same time as the guideline, discussing what technical authors mean by "deprecated" (and related terms).

There were a few questions about where feature removal information comes from. Presently, it looks like removal from the platform is something that happens outside the realm of the specification process. Things get removed from specifications formally, but there's no formal process after that. That happens among vendors, informally, though things like intent-to-unship are a strong signal.

Can we ignore deprecated features?

We went over the idea of pretending that deprecated features don't exist. I noted that deprecated features often come in searches (on MDN, caniuse, Stackoverflow, and elsewhere). It's hard to hide a feature once its part of the platform. There was some advocacy for dealing with the problem directly, instead of ignoring it.

What about not-exactly deprecated features?

XMLHttpRequest (XHR) isn't exactly deprecated, but it has a clear successor: fetch. There's nothing formal that says you should use fetch, but it's an obvious thing to suggest. Is there a possibility of describing features in terms of "use this instead?" I committed to writing a proposal to cover this (I think we should be able to say that a feature is superseded, in whole or in part, in a feature description, independently of its deprecation status).

[ddbeck]

OK, here it is: my proposal for handling discouraged features.

For features that are pending removal from the platform, I think we should do #955 first, since that’s a prerequisite for reporting a likely future state for any feature (discouraged or not).

In the meantime, any feature that would be in the process of active removal would be covered by my proposal for a “discouraged” status, below. That is to say, all pending removal features are discouraged, but not all discouraged features are pending removal.

For all discouraged features, we could do as I've proposed in this Google Doc (feel free to comment or suggest changes). The summary is:

• Publish a new status definition called "discouraged." It would be mutually exclusive with Baseline.

• Produce iconography and usage guidelines for discouraged features that complement Baseline iconography.

• Add two new fields to feature entries:

  • discouraged, with URLs pointing to evidence of discouragement
  • alternatives, with feature IDs pointing to partial or complete substitutes that developers ought to consider using instead

• Replace status.baseline ("high", "low", false) with status.condition strings (baseline-high, baseline-low, limited-availability, discouraged-available, discouraged-limited-availability). This would compel consumers to handle the new statuses in a way that doesn’t falsely report Baseline status. It would also make room for other conditions in the future (e.g., pending removal).

[ddbeck]

I talked to @atopal about my proposal earlier today and he raised some interesting questions. I think it'd be helpful if I could illustrate it with a few examples. I'll try to do that a little later this week.

[Elchi3]

To add more data to this discussion, the following deprecated BCD keys are in real web-features features today and should probably be removed or otherwise be flagged within their features:

• 'api.FontFaceSet.FontFaceSet',
• 'api.DelegatedInkTrailPresenter.expectedImprovement',
• 'api.CanMakePaymentEvent.methodData',
• 'api.CanMakePaymentEvent.modifiers',
• 'api.CanMakePaymentEvent.paymentRequestOrigin',
• 'api.CanMakePaymentEvent.topOrigin',
• 'api.PaymentManager.instruments',
• 'api.PaymentRequestEvent.instrumentKey',
• 'api.PaymentRequest.merchantvalidation_event',
• 'api.PaymentRequest.shippingAddress',
• 'api.PaymentRequest.shippingOption',
• 'api.PaymentRequest.shippingType',
• 'api.PaymentRequest.shippingaddresschange_event',
• 'api.PaymentRequest.shippingoptionchange_event',
• 'css.at-rules.media.prefers-color-scheme.no-preference',
• 'api.SVGAnimateColorElement'

To me they look like they fall into the category of "Features that are being actively removed from browsers".

[ddbeck]

I talked to the MDN folks last week and got some good feedback on reporting this stuff. Briefly, I think the way forward might be something this like:

• Start recording discouraged information on features in a structured way. That is, add a discouraged object to the schema that contains a link to evidence of discouragement and (optionally) references alternative features.
• Ask consumers to use discouraged as a signal to not show a Baseline banner (regardless of status). But in the near-term, they can continue to show the "limited availability" status for those features, in line with the current Baseline status.
• After we have some experience with recording this data, revisit creating discouraged status definition. This way we won't lock ourselves into a particular definition before we've determined that we're producing the data that consumers need to produce useful information for their users.

I'll try to make some demo data for this next week.

[ddbeck]

I'll try to make some demo data for this next week.

I've opened #2388 for this.