Embellish discouraged data with more detail

[ddbeck]

Toward #3210.

In meetings with MDN, @atopal and I have been talking about how to make it possible for MDN to replace MDN-authored and managed deprecation banners with banners automatically presented based on data from web-features. This PR explores two possible additions to the data to satisfy MDN's use case. Those two changes are:

• A pending_removal field (to exaggerate warnings on mutation events and any future platform removals, if they arise). In my initial demonstration, this is a seldom-used boolean that shows active removal from the platform. Here, it applies to mutation events only.
• A removal_date field to exaggerate warnings on mutation events and any future platform removals, if they arise, or to indicate when a feature was removed, if it's gone already.
• A reason field, which briefly explains to developers why the feature is deprecated. If we added this, it would become a required field.

At this point, I'm looking for feedback on the schema. I expect that we'd eventually need guidelines for writing the messages and setting the removal_date field—if you need those guidelines to judge the schema here, please let me know.

[ddbeck]

I don't really know why this was stuffed into Annex B (the spec does not provide more specific text, unlike getYear(), so I just quote from the spec directly.

[ddbeck]

Here's our one removal pending. All pending removal features are discouraged features, but not all discouraged features are pending removal, thus a subordinate key and value here.

[captainbrosset]

Have we talked about what happens once features are removed? Will we then delete the mutation-events.yml file and dist file? I suspect not, since we likely don't want to reuse the ID.

[ddbeck]

We have not, though perhaps we should do so at the same time. My (very briefly considered) guess is that we ought to have some feature-level annotation that says, more or less, "this is historic and you should not show it to developers by default." It would cover both features removed (like this one) but also features that never shipped widely in the first place (import-assertions would be a good example) or got abandoned before making it into a stable release.

Maybe something like retired: true, but I'm reluctant to add a single-use boolean. Something "stringy" would be nice, so we have the option of introducing nuance later, if needed. Maybe a sort of summary field? condition: "normal" | "discouraged" | "pending-removal" | "historic". We'll need to think on this problem a little more.

[captainbrosset]

I like the new reason field. It will make it much easier for consumers of the data to show meaningful content, plus link to the source of truth for that content (instead of just showing a generic discouraged label with a link only).

[LeoMcA]

Thanks for making this buildable locally: it works nicely on MDN: mdn/fred#772

I thought it would be easier to create and maintain this data if it were a removal_date that is either a future date (the expected timeline for removal) or today or a past date (for when it was actually removed).

This works well for our needs.

[Rumyra]

@ddbeck I've had a scan through of the reasons - I think these are all very good, I don't suggest we overthink these - the guidelines look good and they are already a huge improvement to what we have

[ddbeck]

OK, I think this PR is ready for review, with an eye toward landing it soon. Here's what's changed recently:

• I added information about the new fields to the package README file.
• I added reason_html (like description_html).
• I added an assertion to author a removal_date on discouraged features with no support, then set the value on the features where it was required.

[LeoMcA]

Checked out and built locally for testing against MDN: works well, thanks for the addition of the reason_html field too