Update status of BeforeInstallPromptEvent

[jpmedley]

This is actually not being deprecated. It's simply being moved to a different spec. As soon as it gets written it will be here.

From our site:

The Chrome team remains committed to supporting them, and has no plans to remove or deprecate support. web.dev continues to recommend using them to provide a customized install experience.

[Elchi3]

@sideshowbarker given #5960 can you please review this one?

[sideshowbarker]

The problem is, there isn’t actually a spec at https://github.com/WICG/beforeinstallprompt yet — even though it’s been more than a month since these were dropped from the Manifest spec.

There’s also no record anywhere that I could find of any activity at all going on to actually re-specify the features, nor even anybody committed to actively working on a spec.

And the commit message which dropped them from the Manifest spec said this:

the proposal is to remove "beforeinstallprompt" and leave it to browsers to provide better UI to surface installability of web applications

So at this point, to me at least, it’s unclear what the actual plan is for those features.

Should we act on faith that somebody really is going to end up eventually getting around to putting something at https://github.com/WICG/beforeinstallprompt? Or among the implementors is the real plan in fact to just not actually specify any features for this after all?

And that leads me to wonder if at MDN we have a policy or precedent for cases like this.

What I mean is, I wonder whether there’s an MDN policy or precedent for dealing with cases where despite having an indication of intent for some features to be (re)specified somewhere, we don’t actually have any current spec which defines the features — and that’s been the state of things for some time, with no signs that it’s going to change any time soon.

[sideshowbarker]

OK, after reading through the entirety of the w3c/manifest#836 discussion, some things about this are a bit clearer for me now.

However what’s now not as clear to me — even after re-reading https://github.com/mdn/browser-compat-data/blob/master/schemas/compat-data-schema.md#status-information — is what exactly we mean by “deprecated” in the BCD context, vs. “standard_track” and ”experimental”.

But for now as far as this specific case, the reasons I see for not using deprecated: true are:

• it was never a cross-browser part of the web platform to begin with — it’s only been implemented in a single engine — so it’s not a deprecated part of the web platform
• it hasn’t been deprecated in the single engine that supports it; nobody from the Chrome team has said they’re going to remove it or add deprecation warnings for it

On the other hand, as far I can see from the w3c/manifest#836 discussion, both Apple and Mozilla have made it clear that they’re not going to implement it — even if/when it does ever actually end up being re-specified at https://github.com/WICG/beforeinstallprompt.

But that state of things is already reflected by the fact it’s marked as standard_track: false and experimental: true.

So, given all that, I think it’s fine for this change to be merged — as long as everybody agrees that it’s OK for something to be marked deprecated: false in BCD even when it’s:

• not in any current specification
• only implemented in a single engine
• other browser projects are on record as saying they’re not going to implement it

https://github.com/mdn/browser-compat-data/blob/master/schemas/compat-data-schema.md#status-information, for a case like this, seems somewhat ambiguous; it says this:

indicates if the feature is no longer recommended. It might be removed in the future or might only be kept for compatibility purposes. Avoid using this functionality.

Specifically, for this case, and given the definition above, do we want BCD and MDN to indicate:

• this feature is no longer recommended
• developers should avoid this functionality

If we do want BCD to have an indication of those things, then how can that be done other than by marking it as deprecated: true?

If we don’t want BCD to have an indication of those things in this case, then I fully agree it should be marked deprecated: false.

[sideshowbarker]

I guess there’s a related meta-issue that I’ve touched on in my previous comments, and I’m happy to take that to https://github.com/mdn/sprints or https://discourse.mozilla.org/c/mdn/236 for discussion — but for now at point-of-use here too, I want to mention one more related thing:

https://developer.mozilla.org/en-US/docs/Web/API/Window/onbeforeinstallprompt previously had an {{Obsolete_Header}} — which I added, but which has now been removed.

That’s appropriate and I’m 100% OK with it if our plan is to also mark it deprecated: false in BCD.

However, any web developer finding that MDN article now isn’t going to find any indication at the top of that article that it’s a feature which is only implemented in a single browser engine and that no other browsers are planning to support and that isn’t in any current specification.

There’s a discussion at WICG/admin#102 about how to best mark specs that are only implemented in a single engine — and not directly about how the related MDN articles should be marked — but one thing that’s touched on there is unhappiness from browser projects about cases where web developers end up complaining or raising browser bugs asking why the browser hasn’t implemented a particular feature despite it having a spec and despite it being documented in MDN.

So https://developer.mozilla.org/en-US/docs/Web/API/Window/onbeforeinstallprompt seems like a case where — to clearly convey the status to web developers and so then to also address browser-project concerns about how MDN handles cases like this — we’ve got an obligation to developers and browser projects to try to make the MDN article have some very prominent caveat indicators.

Maybe in this case we could do that by adding {{Non-standard_Header}} to the MDN article?

(And maybe also {{SeeCompatTable}}? I’m not sure because I vaguely recall recently seeing some mention somewhere of not using {{SeeCompatTable}} — but maybe I just imagined that…)

For a case like this where it’s already marked standard_track: false in BCD, I would normally just go ahead and mark the MDN article {{Non-standard_Header}}. But in this case I am reluctant to unilaterally make that change until we have agreement here on what we want to be communicating to web developers about the status of this feature.

[sideshowbarker]

About the meaning of deprecated, I’ve since found and read mdn/stumptown-content#306 (comment) which also mentions the lack of clarity about “whether it is deprecation per spec or a browser deprecation”.

[Elchi3]

So, given all that, I think it’s fine for this change to be merged — as long as everybody agrees that it’s OK for something to be marked deprecated: false in BCD even when it’s:

* not in any current specification

* only implemented in a single engine

* other browser projects are on record as saying they’re not going to implement it

Yep, I think per our current semantics this change is fine to be merged as the points you make are arguments for having standards_track: false (which is already set).

Specifically, for this case, and given the definition above, do we want BCD and MDN to indicate:

* this feature is no longer recommended

* developers should avoid this functionality

If we do want BCD to have an indication of those things, then how can that be done other than by marking it as deprecated: true?

If we don’t want BCD to have an indication of those things in this case, then I fully agree it should be marked deprecated: false.

I think we don't want MDN to make a indication here. We want to boldly raise awareness that this is a non-standard / single-engine feature, but ultimately MDN readers would need to decide for themselves if that makes it an avoidable feature or not. If there would be a standardized alternative, this would be different, then MDN would strongly recommend such a feature instead.

Comparatively, we show browser compat data, but we can't indicate "use or don't use" for a given feature, because we don't know the context the MDN reader lives in (e.g. does an MDN reader still need to support IE11 or not?). (we have plans to ask MDN users to provide us with this context, but that's a separate story)

Example: Back when we documented Firefox OS web APIs (say Contact API), we marked it as non-standard but not as deprecated, because in the environment (Firefox OS) it was not deprecated.
So, here it seems similar, BeforeInstallPromptEvent is only present in the Chromium world, so non-standard, but in that world it is not deprecated. MDN readers live in different worlds, if they are Chromium web apps developers, then this doesn't matter to them. If they are cross browser web developers, then non-standard signals them, that this is out of the Chromium world and not usable in their scenario.

Of course, we try to promote open standards and hope to advertise to MDN readers the cross browser world whenever possible. ("To provide developers with the information they need to easily build projects on the web platform" is MDN's mission and "A world where everyone developing for the web follows open standards." is MDN's vision). The reality is, though, that we also want to make information about non-standard, single vendor APIs available as these seem useful to be known by web developers.

However, like on other community wikis, this is where we need different viewpoints and opinions to present relatively neutral documentation as opposed to material published by the company creating the technology. So, I appreciate your thoughts here and am also saying that I'm not making the rules, but that we as a community make them. So splitting this discussion out of this PR to discuss our guidelines and semantics, would be appreciated.

Maybe in this case we could do that by adding {{Non-standard_Header}} to the MDN article?

Yes. I think we can indicate more boldly that this has no specification or that the specification is still very much in progress and super unstable.

About the meaning of deprecated, I’ve since found and read mdn/stumptown-content#306 (comment) which also mentions the lack of clarity about “whether it is deprecation per spec or a browser deprecation”.

Yes, this issue is unresolved. The discussion here might be new input for clarifying that, but I propose we split that into a new issue.

[sideshowbarker]

If we do want BCD to have an indication of those things, then how can that be done other than by marking it as deprecated: true?
If we don’t want BCD to have an indication of those things in this case, then I fully agree it should be marked deprecated: false.

I think we don't want MDN to make a indication here. We want to boldly raise awareness that this is a non-standard / single-engine feature, but ultimately MDN readers would need to decide for themselves if that makes it an avoidable feature or not. If there would be a standardized alternative, this would be different, then MDN would strongly recommend such a feature instead.

OK — makes sense

Comparatively, we show browser compat data, but we can't indicate "use or don't use" for a given feature, because we don't know the context the MDN reader lives in (e.g. does an MDN reader still need to support IE11 or not?). (we have plans to ask MDN users to provide us with this context, but that's a separate story)

Example: Back when we documented Firefox OS web APIs (say Contact API), we marked it as non-standard but not as deprecated, because in the environment (Firefox OS) it was not deprecated.
So, here it seems similar, BeforeInstallPromptEvent is only present in the Chromium world, so non-standard, but in that world it is not deprecated. MDN readers live in different worlds, if they are Chromium web apps developers, then this doesn't matter to them. If they are cross browser web developers, then non-standard signals them, that this is out of the Chromium world and not usable in their scenario.

Right, that too makes sense

Of course, we try to promote open standards and hope to advertise to MDN readers the cross browser world whenever possible. ("To provide developers with the information they need to easily build projects on the web platform" is MDN's mission and "A world where everyone developing for the web follows open standards." is MDN's vision). The reality is, though, that we also want to make information about non-standard, single vendor APIs available as these seem useful to be known by web developers.

I agree on that too. I think that the for web developers, there is big value in having a single canonical place where they can go to get information for web features exposed by browser engines. I would not want to see things ever regress back into a situation where we had N different browser vendors redundantly hosting documentation about web features at their own domains.

However, like on other community wikis, this is where we need different viewpoints and opinions to present relatively neutral documentation as opposed to material published by the company creating the technology. So, I appreciate your thoughts here and am also saying that I'm not making the rules, but that we as a community make them. So splitting this discussion out of this PR to discuss our guidelines and semantics, would be appreciated.

OK, will do that

Maybe in this case we could do that by adding {{Non-standard_Header}} to the MDN article?

Yes. I think we can indicate more boldly that this has no specification or that the specification is still very much in progress and super unstable.

Right — as I've said, I think in general we have an obligation to try to convey the implementation/standards status as clearly as possible. So I am enthusiastic about helping to find good/new ways to do that.

About the meaning of deprecated, I’ve since found and read mdn/stumptown-content#306 (comment) which also mentions the lack of clarity about “whether it is deprecation per spec or a browser deprecation”.

Yes, this issue is unresolved. The discussion here might be new input for clarifying that, but I propose we split that into a new issue.

OK