Un-deprecate navigator.platform (was: Replace Deprecated_Header in navigator.platform doc and adjust navigator.userAgentData.platform note wording)

[sideshowbarker]

Fixes #14429. For the navigator.platform article, this change does the following:

• Drop the Deprecated_Header macro.
• Add admonishments that navigator.platform should be avoided in favor of feature detection.
• Relegate mention of (equally-bad) navigator.userAgentData.platform to just being a See also.
• Add an example of the single known good case where using navigator.platform isn’t completely bad.

Related BCD change: mdn/browser-compat-data#15599

Previous/now-superseded issue description…

• 4db8611 Adjust wording of note about navigator.userAgentData.platform
• f73b2d9 Replace Deprecated_Header in navigator.platform doc

Given navigator.userAgentData.platform is currently only supported in Blink, we shouldn’t be strongly “recommending” it; so 4db8611 drops the “recommended” and instead just points out navigator.userAgentData.platform as an alternative — while changing the “not yet supported by some major browsers” wording to instead more accurately state it’s “not yet supported by most browsers”.

And given that navigator.platform is not formally deprecated by the spec, f73b2d9 replaces the Deprecated_Header macro and its boilerplate text with some more-appropriate alternative pseudo-boilerplate text that’s intentionally broadly worded in such as way as to not be specific to just the navigator.platform case but instead worded for the general case where we want to warn web developers to avoid using a particular feature.

See also #12017 (comment).

[github-actions]

Preview URLs

• https://pr14452.content.dev.mdn.mozit.cloud/en-US/docs/Web/API/Navigator/platform

Flaws

URL: /en-US/docs/Web/API/Navigator/platform
Title: navigator.platform
on GitHub
Flaw count: 2

• macros:
  • wrong xref macro used (consider changing which macro you use)
  • wrong xref macro used (consider changing which macro you use)

External URLs

URL: /en-US/docs/Web/API/Navigator/platform
Title: navigator.platform
on GitHub

No new external URLs

(this comment was updated 2022-03-31 12:21:10.854391)

[wbamberg]

Since I complained about this already, I'm happy to see this! Approving but leaving open in case @hsivonen has a comment.

[hsivonen]

Thanks. I suggest dropping both instances of the word "yet".

[sideshowbarker]

Thanks. I suggest dropping both instances of the word "yet".

👍 Made it so in 57fdcf0

[sideshowbarker]

Marking this as Draft so that we make sure not to merge it until we also get resolution on some of the details discussed in #14429 (comment)

[hsivonen]

On further thought, instead of just suggesting the code be updated while also mentioning a Blink-specific API for also doing the discouraged thing it would make sense to mention that in general, Web developers should feature-detect relevant things when applicable and not care about the platform as a general rule.

[sideshowbarker]

OK, in light of the spec change at whatwg/html#7762, I’ve gone ahead and completely re-worked this patch to instead do the following:

• Drop the Deprecated_Header macro.
• Add admonishments that navigator.platform should be avoided in favor of feature detection.
• Relegate mention of (equally-bad) navigator.userAgentData.platform to just being a See also.
• Add an example of the single known good case where using navigator.platform isn’t completely bad.

Related BCD change: mdn/browser-compat-data#15599

On further thought, instead of just suggesting the code be updated while also mentioning a Blink-specific API for also doing the discouraged thing it would make sense to mention that in general, Web developers should feature-detect relevant things when applicable and not care about the platform as a general rule.

In the updated patch, I added some language which tries to give that advice.

So @hsivonen and @wbamberg, if you could both review the updated patch, I’d appreciate it.

[teoli2003]

@sideshowbarker @hsivonen Feel free to ask for my review when this is ready to land. That way I know you are done and we can abide by our rule that this is not landed by the author of the PR.

[sideshowbarker]

@sideshowbarker @hsivonen Feel free to ask for my review when this is ready to land. That way I know you are done and we can abide by our rule that this is not landed by the author of the PR.

Thanks — will do

[hsivonen]

Thanks. I can't actually pick the "Approve" option, because I'm not an official reviewer for this repo.

[sideshowbarker]

@teoli2003 Having gotten @hsivonen’s r+ on this, I think it’s ready to merge. I still hope @wbamberg can take a look at it post-merge and if there’s anything he notices that we missed, I’ll be happy to do a follow-up PR

[teoli2003]

Just a tiny change on the first line to make it coherent with the whole of MDN.

[teoli2003]

I'm merging. We can do more changes in follow-up PRs if needed.

Thanks, @hsivonen, @sideshowbarker and @wbamberg to have this sorted out! 🎉

[hamishwillee]

@sideshowbarker @teoli2003 Does it make sense to remove the info/links to NavigatorUAData.platform?

I understand the desire to point to feature detection, and the reasoning why navigator.platform shouldn't be deprecated.

But despite the spec change to navigator.platform my take is that you would be much better off using NavigatorUAData.platform. The user hints are more fully designed and specified - and while they aren't on all platforms, neither is the value of navigator.platform reliable on any platform.

[sideshowbarker]

@sideshowbarker @teoli2003 Does it make sense to remove the info/links to NavigatorUAData.platform?

I think it doesn’t make sense to remove it completely — which is why I moved it to being a See Also — but I think given the current state of things, it doesn’t make sense to give it as much prominence as it had.

I think giving it that amount of prominence made sense when we had navigator.platform marked as Deprecated — because in that case, we actually had people asking, OK, if this is deprecated, then what’s the alternative?

But as the fact that #14429 was raised kind of shows, we create a different problem when when we give this particular alternative the kind of prominence we were giving it — especially if we say it’s recommended.

But despite the spec change to navigator.platform my take is that you would be much better off using NavigatorUAData.platform. The user hints are more fully designed and specified

One thing we need to recognize is the people who work on non-Blink/Chrome browsers projects are not super happy if MDN promotes the use of some feature to developers when the current reality of that feature is that in practice it’s a Blink-only feature — even when that feature has a well-intentioned actively-maintained spec.

But it doesn’t matter how good the spec is if other browser projects aren’t implementing and it and aren’t even showing interest. And in the specific case of Client Hints, there was even at one time some discussion about having https://mozilla.github.io/standards-positions/ list is a Harmful.

It’s now marked “non-harmful” there but anyway we need to recognize that the Mozilla engineering team does not seem to be any interest in ever implementing Client Hints.

And while the Safari/WebKit team also doesn’t seem opposed to ever implementing Client Hints (see https://lists.webkit.org/pipermail/webkit-dev/2020-May/thread.html#31195), working on actually implementing doesn’t seem to be any significant priority for them — to the point that they haven’t even bothered to list it at https://webkit.org/status/.

my take is that you would be much better off using NavigatorUAData.platform

After looking through a lot of navigator.platform usages in Stack Overflow questions and answers in GitHub code, I can say that in nearly all cases where people are using navigator.platform in code, they are not using it for good reasons — and the kinds of things they are doing are things that we actually want to discourage developers from doing.

The same goes for ways in which somebody might use NavigatorUAData.platform — the underlying problem with both properties is that it’s fundamentally a bad idea to try to be finding out information about the user’s environment rather than only relying on feature detection.

I am aware of only one single case in which it makes sense to try and get information about the user’s platform — and that’s the deciding-on-which-modifier-key-to-advise-to-the-user case which I added an example for in the patch here.

Other than that one case, I’m not aware of even a single other best-practice case of something to do in code based on finding out information about the user’s platform — whether by using navigator.platform or with Client Hints.

and while they aren't on all platforms, neither is the value of navigator.platform reliable on any platform.

The key big differences are that navigator.platform is actually implemented in every browser engine (even if its reliability may vary), and navigator.platform is part of a standard that’s gone through the process of getting agreement and endorsements among multiple browser projects.

[hamishwillee]

Thanks for the detailed explanation. I can get on board with it being a "see also".

[hsivonen]

Thanks!