Support banners/headers

[wbamberg]

See mdn/yari#350.

I had thought that this would be doable with no changes in stumptown-content because the underlying info is in BCD. But it might be better to expose BCD's "status" in a more accessible place in the JSON. My suggestion in that case would be to include it in the body object, as a new item like:

{
    "type": "status",
    "value": [
        "non-standard", "deprecated"
    ]
}

...that is, a type of "status" and a value which is an array including any of "non-standard", "deprecated", and "experimental". I think if none of these apply the whole item could be omitted.

Then this issue would be fixed by making updating build-json to pull that info out of the BCD, and adding this new item to the built JSON.

@Elchi3 , @ddbeck , what do you think?

[wbamberg]

One thing is that BCD has "standard_track", which inverts the meaning from "non-standard". I think it would be nice to represent this in the JSON as "non-standard", though, since that's the case worth noting.

Also, it's a bit upsetting that "non-standard" duplicates information from the specifications property (see #126 (comment)). I don't know if we should try to address that.

[Elchi3]

Then this issue would be fixed by making updating build-json to pull that info out of the BCD, and adding this new item to the built JSON.

I think this would be great and I think short term this would get us to remove the macros nicely.

I also want to briefly give some more thoughts on banners or status properties. This stuff has been underspecified for a long time and so over in BCD, we've had discussions about how to best go about this. Some comments on how I see this:

• deprecated is mostly good as is. The issue that comes up is that sometimes it is a bit unclear who deprecated the feature and what it means. So, whether it is deprecation per spec or a browser deprecation and if it will ever be removed (usually it won't be removed for web compat reasons, but sometimes it will be [see app cache]).
• obsolete is a status term we've banned from MDN. It used to mean "deprecated and no longer implemented", but implementation status is compat data, so we've stopped using it. If you want to communicate "do not use!", use deprecated. I would remove all macros that call things "obsolete". The term is already banned in BCD (RFC: Deprecated vs. Obsolete browser-compat-data#265).
• non-standard is a thing that is indeed duplicated with the specifications property and when we've started to add spec urls to BCD, I already proposed to get rid of non-standard. I still think we should remove this and show a non-standard banner according to the new specifications property that we've designed a while ago (instead of a URL you give it the string "non-standard").
• experimental is a property that I'd like to rename to unstable. Rachel Andrew has done great research on this for CSS and I think this model can apply to other areas as well. Basically we've removed "experimental" banners almost everywhere, but there a few cases where the features aren't stable and these should be marked and warned about. (c.f. Decide what to do with remaining "experimental" CSS features browser-compat-data#5392). I don't know when we can change this in BCD, but I hope to prioritize this sometime in 2020.

I don't want to derail this, though. Maybe the semantics work on status properties can happen in BCD and stumptown-content will pick this up in the body as you propose. In other words, maybe for now don't worry about all this semantic discussions that we need to get through and just pull whatever comes from bcd in the status block (and also take into account the specfications property in stumptown).

[wbamberg]

I've been thinking about this and here's the weird thing.

Currently, pages point to recipes. A recipe lists the things (ingredients) that should be present in a doc, and we expect (for data ingredients anyway) that the doc's front matter contains an item with the same name as the ingredient. So for example, we have a recipe item data.browser_compatibility and we then expect to see a browser_compatibility front matter item in the page. So an ingredient is a signal to the author to include this thing in the docs. We then use this ingredient set to drive the JSON building: both the things we look for and the order in which we build the JSON.

I like all this.

So, if there's expected to be a status item in the JSON, should there also be a data.status ingredient in the recipes? It seems like there should, otherwise we're being inconsistent here. But since we're actually setting the contents of this item from data contained inside other front matter items (specifications and browser_compatibility), then there's no corresponding front matter item, and that also seems inconsistent and confusing for writers.

---

I can think of three options:

1. treat status as a proper ingredient, in recipes, in front matter, and in built JSON. This implies writers have to include a status item in front matter that essentially duplicates specifications and browser_compatibility, or that it just empty. Both of these seem weird. But it makes everything else non-weird.

In defence of this option, we could imagine a world where BCD didn't include status, and then this would be an extra datum the writer has to supply, and then we would have a front matter item for it. In fact I don't think BCD should include status, but I think that ship has sailed.

2. don't expose status anywhere in stumptown-content. Not in recipes, or in front matter, or in built JSON. Instead, the renderer has to find the data in specifications and browser_compatibility. This tends to break the way the renderer wants to build pages, where it can just walk through the JSON.

In defence of this option, it seems likely that the renderer will have to abandon this approach eventually. For example, we would like to include a "BCD summary" thing at the tops of pages. If we do this, are we really going to do it by having build-json insert a new JSON item that essentially duplicates browser_compatibility?

3. A half-way house: don't represent status in recipes, or in front matter. But have build-json magically insert it into the JSON. This keeps both ends - authors and the renderer - from being weird, but makes build-json weird.

@ddbeck , @Elchi3 , any wisdom?

---

(Edited to add options, after thinking a bit more.)

[ddbeck]

To further complicate things, what about a fourth option:

In recipes, we use prose.some_section to show that we expect some Markdown (and, in scraping, some H2 in the wiki) and data.some_field to show that we expect some frontmatter. Can we use some third notation to show that an ingredient arises from some other authored thing? Perhaps generated.status or derived.status would communicate that the author isn't meant to create that content themselves, but still lets us include status in the recipe.

(Some day, I think it will be good to generate documentation for authors and for JSON consumers based on the recipe file itself. What the recipe means varies a lot, depending on which side of build-json you're on.)

[peterbe]

I'm a little bit weak on context but I think I can understand the scary implicitness of it working even if the front-matter doesn't have something that it's supposed to have.
One option would be to have, in the front-matter, status: generated-from-bcd

Hypothetically, would be it possible to overide what the the "BCD computation" does and manually type it? Like this status: deprecated, almost-overdue, experimental-node

[wbamberg]

To further complicate things, what about a fourth option:

In recipes, we use prose.some_section to show that we expect some Markdown (and, in scraping, some H2 in the wiki) and data.some_field to show that we expect some frontmatter. Can we use some third notation to show that an ingredient arises from some other authored thing? Perhaps generated.status or derived.status would communicate that the author isn't meant to create that content themselves, but still lets us include status in the recipe.

I like this (especially generated). It's expressive of what's going on, doesn't lie, and is simple for both authors and renderers. I felt in the meeting today some sympathy for the idea that status might not be best placed in BCD, and this option also seems to offer us a route towards making status a front matter ingredient, if we ever chose to do that.

I'm a little bit weak on context but I think I can understand the scary implicitness of it working even if the front-matter doesn't have something that it's supposed to have.
One option would be to have, in the front-matter, status: generated-from-bcd

Yes, we could do that too. But then all authors would have to type the same thing over and over again.

Hypothetically, would be it possible to overide what the the "BCD computation" does and manually type it? Like this status: deprecated, almost-overdue, experimental-node

I don't think we would want to do this, because that breaks the idea of a single source of truth.