Add discouraged to schema (and with statement demo feature)
#2388
Conversation
ddbeck
requested review from
autonome,
jamesnw,
Elchi3,
foolip,
atopal and
captainbrosset
github-actions
bot
added
feature definition
ddbeck
added
the
minor version required
| baseline: false | ||
| support: | ||
| chrome: "38" | ||
| chrome_android: "38" | ||
| edge: "12" | ||
| firefox: "48" | ||
| firefox_android: "48" | ||
| safari: "10" | ||
| safari_ios: "10" |
There was a problem hiding this comment.
Given the current Baseline definition, this is correct. That said, I expect consumers (like MDN and caniuse) to choose to suppress the Baseline information when there's a discouragement.
schemas/data.schema.json
Outdated
| "discouraged": { | ||
| "additionalProperties": false, | ||
| "description": "Whether developers are formally discouraged from using this feature", | ||
| "properties": { | ||
| "according_to": { | ||
| "description": "Links to a formal discouragement notice, such as specification text, intent-to-unship, etc.", | ||
| "items": { | ||
| "description": "URI", | ||
| "format": "uri", | ||
| "type": "string" | ||
| }, | ||
| "type": "array" | ||
| }, | ||
| "alternatives": { | ||
| "description": "IDs for features that substitute some or all of this feature's utility", | ||
| "items": {}, | ||
| "type": "array" | ||
| } | ||
| }, | ||
| "required": [ | ||
| "according_to" | ||
| ], | ||
| "type": "object" | ||
| }, |
There was a problem hiding this comment.
This is a semver minor event.
|
To stress test this a bit, I went through the CSS keys that are deprecated and standard track. I'm thinking I'll create the following features: Clipalternative: `clip-path`
Media Queries (deprecated)alternative: media-queries
Writing mode (deprecated)alternative: writing-mode
color-adjustalternative: print-color-adjust
SVG (deprecated)
IME Mode(no alternative)
text-decoration-line :blinkalternative: animations-css
word-break: break-wordalternative: Use overflow-wrap: anywhere instead (note we only can link to overflow-wrap)
overflow: overlayalternative: Use overflow: auto instead (note we can only link to overflow-shorthand)
Note that the list isn't long (and makes me want to double check my query), but it does surface a question around alternatives- What should we do when the alternative is just a single key within a larger feature? Can we mention the alternative in the description when possible? |
There was a problem hiding this comment.
I like this.
Just left one comment to help consumers.
My more important general comment is how do we ensure that this isn't used for things we don't agree with. Because this is not data we can really check, there isn't much, beside thorough reviewing, to ensure this isn't used incorrectly.
Not sure what incorrect usage there could be, but I want to avoid, for example, cases where someone marks a feature as discouraged because it's just not implemented in browser X, and browser X vendor opposes that feature.
schemas/data.schema.json
Outdated
| "items": { | ||
| "description": "URI", | ||
| "format": "uri", | ||
| "type": "string" | ||
| }, |
There was a problem hiding this comment.
What do you think about making this an object with both URI and link text?
Having the URI only forces consumers to come up with some link text on their own (or display the full URI, which isn't great).
This would avoid patterns like: "Discouraged, click here to learn why".
There was a problem hiding this comment.
I think this is a good idea, but I'm slightly concerned about us making guesses about what kind of text that consumers would like. I could imagine several different plausible ways to turn discouragement citations into text (I had a try below). I think it might be better to see how MDN and others actually end up using this and what works with developers, before committing to a single way of doing link text.
I do think we should revisit this, like the reason enums.
Possible ways to show this stuff:
-
Spec owner:
Most developers shouldn't use
within new websites (according to TC39). Consider using Destructuring instead. -
Wikipedia style:
Most developers shouldn't use
within new websites[1]. Consider using Destructuring instead. -
Fetching the page title:
Most developers shouldn't use
within new websites (see ECMAScript® 2025 Language Specification). Consider using Destructuring instead. -
Domain name:
Most developers shouldn't use
within new websites (tc39.es). Consider using Destructuring instead.
All are possible without a handwritten text field.
That is a concern for sure, and it's independent of the wording. Even going with "deprecated", unless that comes out of the standardization process, it's not clear what should happen next. If one vendor considers an API as deprecated, but another one doesn't. Is that feature deprecated? Not hypothetical either, see Battery Status. |
|
Maybe we limit this to cases where it's unambiguous (either from the spec or alignment of vendors) and explicitly exclude cases where there is disagreement for now? |
There was a problem hiding this comment.
I've applied this to #2076 and it works for me. I think this could land and "reason" could be added later among other things.
Suppressing the baseline info should probably be strongly encouraged somehow, but I guess it is fine to expose false for now. Adding "discouraged" as a new baseline enum would certainly be more bold and maybe that would be the correct thing but maybe not now to avoid being too disruptive. I guess it would still be a possibility to change it later in a breaking release if desired.
|
This PR was discussed during today's WebDX CG call (minutes). |
Co-authored-by: James Stuckey Weber <[email protected]>
github-actions
bot
added
the
documentation
|
I've pushed some guidelines and changes to the README for consumers. I hope it answers most of the remaining questions.
Eventually, I think we should have a way to refer to inner/sub-features, but I don't think we have to have it here. I suspect that after we've enumerated the discouraged features we can revisit this more easily. For now, I think we can satisfy the basic case of "see also: [something else to use instead]" without providing a detailed explanation for what we're referring to, specifically.
I included some text covering this in the new guidelines. The main thrust of it is: only set |
Co-authored-by: James Stuckey Weber <[email protected]>
docs/guidelines.md
Outdated
| Mark a feature as discouraged when: | ||
|
|
||
| - The specification adopts clear language directing developers to stop using that feature or to prefer to an alternative. | ||
| This is often through terms like "deprecated", "obsolete", "legacy", or "non-standard." |
There was a problem hiding this comment.
I would omit the "non-standard" part here. There are many non-standard (yet) features that are not discouraged, per se.
There was a problem hiding this comment.
OK, I've removed this with fc94af6. I think it's true—particularly when a spec absorbs some but not all functionality from a non-standard predecessor—but it probably doesn't add clarity here (without more explanation).
|
FYI: I'm planning to merge this PR after the last BCD and web-features releases of the year, probably the afternoon of Friday, December 20. |
* feat(baseline): hide banner if discouraged web-platform-dx/web-features#2388 * cargo fmt
ddbeck
removed
the
minor version required
This adds
discouragedto the schema. The idea here is that consumers would be able to show something like an MDN deprecation banner, saying that a feature is discouraged from use (citing a source) and suggesting an alternative (if one exists).There are a couple of things missing here:
discouragedand set usefulaccording_toandalternativevalues.Someday, I'd like to have a proper status (with iconography) for this condition that would take the place of Baseline for such features. This is a prerequisite for doing this, but doesn't actually affect the Baseline definition today.
See also: #311