Embellish discouraged data with more detail
#3193
Conversation
github-actions
bot
added
the
feature definition
| @@ -2,6 +2,7 @@ name: Accessor methods | |||
| description: The `__defineGetter__()` and `__defineSetter__()` methods of objects bind a function to a property, which is called on setting or reading the property. | |||
| spec: https://tc39.es/ecma262/multipage/fundamental-objects.html#sec-object.prototype-legacy-accessor-methods | |||
| discouraged: | |||
| reason: TC39 included accessor methods in Annex B of the ECMAScript specification, which covers JavaScript features with "one or more undesirable characteristics and in the absence of legacy usage would be removed." | |||
There was a problem hiding this comment.
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.
| @@ -4,8 +4,11 @@ description: Mutation events like `DOMSubtreeModified`, `DOMNodeInserted`, or `D | |||
| spec: https://w3c.github.io/uievents/ | |||
| group: dom | |||
| discouraged: | |||
| pending_removal: true | |||
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
ddbeck
added
enhancement
|
I like the new |
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:
pending_removalfield (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.reasonfield, 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
pending_removalfield—if you need those guidelines to judge the schema here, please let me know.