Add "deprecated" banner based on BCD front matter (and fall back to tag)

[wbamberg]

(@peterbe asked me to file this, so here goes :) see also https://github.com/mdn/yari/discussions/2905 and https://github.com/mdn/yari/discussions/2905#discussioncomment-618185 in particular)

At the moment we signal deprecation in various ways:

• on the page for the deprecated thing, we have:

  • a block-level banner, added manually via the Deprecated_Header macro (e.g. String.prototype.blink)
  • it's visible in the BCD table for the feature, if BCD marks it as deprecated

• on links to the deprecated thing, we have:

  • in prose content, an inline badge, added manually via the Deprecated_Inline macro (e.g. https://github.com/mdn/content/blob/2d7722a59a0c07fde6197f340a845e625faef175/files/en-us/web/api/element/index.html#L406).
  • in sidebars, an inline badge added automatically based on the page's "Deprecated" tag

So that's drawing on three different sources to know whether a thing is deprecated. It would be good to rationalize this. In general I think BCD is better-maintained than tags or the manually added macros. Recently we have started adding the BCD query into front matter and extending Yari to build the compat table and the spec table from that data, if it is present. So why not extend this further, and make Yari generate the "Deprecated" banner based on BCD?

The basic plan looks like:

1. When Yari builds the page it looks for the browser-compat front matter key.
   • If browser-compat is there, and indicates "deprecated", it adds the "Deprecated" banner.
   • If browser-compat is not there, Yari checks the page tags for "deprecated". If the page is tagged "deprecated", Yari adds the "Deprecated" banner.
2. Change the {{Deprecated_header}} macro to make it a no-op if the browser-compat front matter is present.
3. Add the BCD front matter property to as many pages as is appropriate.
4. Once we've finished adding the BCD front matter property, retire the {{Deprecated_header}} macro.

This issue is for the first two of these. The third can happen in parallel.

This plan keeps the "deprecated" tag around indefinitely, but only as a backup for pages that don't have BCD but might still want to indicate deprecation.

@hamishwillee , @ddbeck , @Elchi3 , @Rumyra, @teoli2003 you might be interested in this or even better you might see fatal problems with it!

See also:

• Auto-add deprecation marker for API item if known #3818
• Use deprecation flag from BCD #2138

[hamishwillee]

Yes to all of the above. It makes sense. This is a better specced duplicate of what I posted in #3818

The things I'd add to this:

• It isn't just Deprecated - the same things apply to Experimental and Non-Standard (note the macro for Experimental has a different name).
• It is possible for a page to be all three things - experimental, deprecated, non-standard. Chris argued in some discussions that if you have deprecated header then you should omit the other headers. That should be discussed.
• Deprecated/Experimental/Non-standard also add the little icons to the sidebar, which is great. That should not be lost.
• Deprecated/Experimental/Non-standard should automatically add the little icons to any Xref or manually created page links to API items (do not currently). This would allow for immediate removal of the deprecated_inline and friends macros. Perhaps you could have an optional argument to disable this but you almost always want it. Again, if it is deprecated, that might be all you need to display inline - do you further care if it is experimental too?
• Is it possible to also tag for read-only to get rid of the read-only inline?
• Are there any other forms of automated inline tagging - "optional"?

[ddbeck]

This plan works for me. A couple of additional notes:

When Yari builds the page it looks for the browser-compat front matter key

I read this and thought there were three distinct states:

1. Compat-driven state: browser-compat is set, valid, and complete (i.e., there's a front matter string, it refers to a valid feature, and the feature contains the status data)
2. An error state: browser-compat is set to an invalid feature identifier
3. Fallback state: browser-compat is not set, or the data lacks status.deprecated (e.g., WebExtensions data doesn't require the status block), so use the backup tag (if applicable)

Not sure what should happen in that second state. Feels sort of wrong to use the backup tag in that case, which feels more broken than intentional

It isn't just Deprecated - the same things apply to Experimental and Non-Standard (note the macro for Experimental has a different name).

I'm not enthusiastic about doing all of this at once (or at least, following the same pattern). I'm skeptical that the data quality for experimental is as good as deprecated (see mdn/browser-compat-data#9933 for more details). Non-standard has a slightly different story which is, more or less: prefer using spec_url to drive this instead.

[peterbe]

It isn't just Deprecated - the same things apply to Experimental and Non-Standard (note the macro for Experimental has a different name).

I'm not enthusiastic about doing all of this at once (or at least, following the same pattern). I'm skeptical that the data quality for experimental is as good as deprecated (see mdn/browser-compat-data#9933 for more details). Non-standard has a slightly different story which is, more or less: prefer using spec_url to drive this instead.

I agree with both "sentiments" here. I think we should consider making "deprecated" a value rather than a key.
Each document has an array of "sections". Most of them are "prose" but there's special types like browser_compatibility and specifications too. So I think we should consider adding another one of those and then the Yari document renderer doesn't need to make a special case. E.g.

    "body": [
      {
        "type": "status",
        "value": {
          "id": "deprecated"
        }
      },
      {
        "type": "prose",
        "value": {
          "id": null,
          "title": null,
          "isH3": false,
          "content": "<p><strong><code>BigInt</code></strong> is a built-in object whose constructor returns a....</p>"
        }
      },
      {
        "type": "prose",
        "value": {
          "id": "Description",
          "title": "Description",
          "isH3": false,
          "content": "<p>...</p>

That way it'll be treated as just another "section" and it'll have a so-called "ingredient" component that knows how to render that.

With that out of the way, I think we should NOT inject things into the document that we don't know for certain. E.g.

      {
        "type": "status",
        "value": {
          "id": "experimental"
        }
      },

...should not appear just because the doc happens to have the Experimental tag.
At least not until we have a confident way to determine that fact.

[peterbe]

I'll need to sleep on it a bit but I like the idea that we can ask the document, in multiple ways "Are you deprecated?" and it's all the same independent of the usage (e.g. sidebars vs. macro links vs. rendering the doc).
And because it could be costly to query this fact repeatedly, we need to implement it in a way that it's overly expensive to find this out over and over in places like the sidebars.

[Rumyra]

Thoughts:

• Automating deprecated is such great idea 😎
• Automating experimental and non-standard would also be great, but agree we need a good way of determining experimental
• I agree with Chris that if something is deprecated the information of experimental or non-standard isn't particularly important, which I think lends itself to @peterbe 's status suggestion

[hamishwillee]

Yes to ^^^ and @Rumyra summary - in particular support the idea of some kind of combined status.

Further thoughts

• Re "2" How we determine whether something is experimental is an "orthogonal question" - ie. I've been told that it is "when supported by 2 major browser engines, but it really doesn't matter for this discussion what process we use. I think we would all agree that it is a useful category so we need to report it in some way. My take is that it is better for "ye average author" to understand what is going on if we handle this consistently with the other flags like deprecation. Even though BCD data quality for experimental is not as good, that's also true on MDN.
• @ddbeck re your comment on what happens if the browser-compat is invalid.
  • In this case I think that you'd have to respect the intent to use browser data - so even if there is a tag that provides the information you'd need report the information as unavailable. However if the browser data is valid and but the specific info is missing in compat then you'd use tags (if available)
  • @peterbe We should add good flaw reporting for all these cases - e.g. invalid browser compat, compat or specifications macros used but browser compat empty or invalid. Specification macro used but no spec_url etc.

[wbamberg]

One comment on this bit, that I forgot:

I'll need to sleep on it a bit but I like the idea that we can ask the document, in multiple ways "Are you deprecated?" and it's all the same independent of the usage (e.g. sidebars vs. macro links vs. rendering the doc).

I don't think we should be adding little deprecated icons, or whatever, on links appearing in content. I think we should definitely add banners, and people seem to like the icons in sidebars, so OK, but I think it would look really distracting to add them whenever we link to a page in normal content.

[hamishwillee]

@wbamberg I see your point re ^^^^ but I think that we would find it better if we were distracted.

The reason I suggested this was that

• I keep seeing issues like "you used this deprecated thing in example", or you "talk about this thing but it is deprecated". Having the icon reminds this team that there is something to clean up.
• When we add an item in the interface page we have to add the inline markup for deprecated or whatever. That's two places where we are now having to track state. One is better.

It would be interesting to be able to review what it might look like, or at least to be able to opt-in or opt-out of auto insertion of the icons (perhaps via macro).