Skip to content

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

Open
@ddbeck

Description

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.

Activity

atopal

atopal commented on Aug 18, 2023

@atopal
Collaborator

That sounds good to me.

ddbeck

ddbeck commented on Nov 1, 2024

@ddbeck
CollaboratorAuthor

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

ddbeck commented on Nov 5, 2024

@ddbeck
CollaboratorAuthor

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

ddbeck commented on Nov 5, 2024

@ddbeck
CollaboratorAuthor

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

Elchi3 commented on Nov 12, 2024

@Elchi3
Collaborator

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

ddbeck commented on Nov 29, 2024

@ddbeck
CollaboratorAuthor

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

ddbeck commented on Dec 3, 2024

@ddbeck
CollaboratorAuthor

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

I've opened #2388 for this.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions

      Record discouraged status (e.g., obsolete, deprecated, legacy, etc.) · Issue #311 · web-platform-dx/web-features