Should we make deprecation more prescriptive?

[Yoav Weiss]

Hey folks,

When thinking about a recent removal attempt, a few things we could've done better come to mind:

1) Pages using the API would got console warnings, but not depreciation reports. It seems like deprecation report could be a good way for e.g. Enterprise folks that opt out of reporting to become aware of deprecations down the line.

2) While the removal was properly announced on blink-dev ahead of time, many folks were surprised by it.

Re-examining (1) in past deprecations, it seems like it's a common issue, and one we could do better on. (2) seems like another place where we can tighten our requirements and require more developer-facing documentation, to reduce future surprises.

Up until now, we relied on the developers to know what to do in terms of deprecation, but it may be good to be more prescriptive?

Seems to me like we could:
* Require that deprecation reports are sent, on top of console errors or devtools issues, and include that as a checkbox item in the deprecation/removal templates
* Require documentation changes and/or articles announcing the deprecation and removal as part of the process
* Something else?

What do y'all think?

Cheers,

Yoav

[Mike Taylor]

Depending on the type of deprecation, requiring some kind of outreach in the form of filing issues on popular libraries or frameworks known to use the feature seems useful, linking back to articles, etc. (bonus points for sending in patches if a recommended alternative is known).

[Rowan Merewood]

I would like to express strong support for this (the encouraging of Deprecation reports specifically, though I am also a fan of preemptively reaching out to affected libraries/frameworks).

My feeling is that there is definitely ecosystem work to do in raising awareness and support for receiving reports, but if we can provide a consistent and predictable process here then that helps generate ecosystem motivation. Ensuring shared strings, identifiers, and general consistency across DevTools, Reports, and documentation is also incredibly helpful from a debugging perspective. Both for individual developers diagnosing an issue, monitoring wider channels (like StackOverflow, etc) to catch wider impact, or just anyone who sees the string and can pop it into a search engine. So, perhaps a standard trio of linked templates for a report message, DevTools deprecation Issue, and documentation page(if that's more than Chrome Status)?

I understand it may also not be appropriate for all deprecations (too many false positives, etc.) but I would be keen to see if suggested as the default approach and individual I2Rs should explain if/why it's not included.

[Jason Chase]

In Chromium, we already have a centralized implementation to provide consistency in recording the use of deprecated features (CountDeprecation). This doesn't seem to be documented very well (only a brief mention in http://dev.chromium.org/blink/launching-features). This implementation will generate both a console message and a deprecation report, using the same info.

With the implementation updated to report DevTools issues (instead of console messages), part of the process could be reduced to "have you implemented a call to CountDeprecation?". As in crbug.com/834238, we still need process to ensure the appropriate follow through and such.

I definitely agree there needs to be ecosystem activation to consume deprecation reports, and all of the other outreach suggestions. I think with a requirement to use CountDeprecation, it should ensure a minimum bar for communication and consistency, with little effort on the part of Chromium developers.

Thanks,

Jason

--
You received this message because you are subscribed to the Google Groups "blink-api-owners-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to blink-api-owners-d...@chromium.org.
To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/blink-api-owners-discuss/93ad6d98-64f2-40a5-85bf-ea423092c30fn%40chromium.org.

[Aleks Totic]

If you are looking to increase developer visibility before depreciation, I know that many developers monitor window error handlers.

Reporting usage of about to be depreciated features to window error handler would get their attention.

It'd also annoy many, so I am not sure whether this is a good idea or not.

Aleks

--

You received this message because you are subscribed to the Google Groups "blink-api-owners-discuss" group.
To unsubscribe from this group and stop receiving emails from it, send an email to blink-api-owners-d...@chromium.org.

To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/blink-api-owners-discuss/CAL5BFfXhMnEDDB_6MQN8WAvXLiK3edeN99SDUomHZ0AuqFh9ew%40mail.gmail.com.

[Greg Whitworth]

This won't surprise Yoav, but I am very much in support of improving the process. One thing that I'd like to see also is coordination with other browser vendors when necessary. This should increase reach in tooling as well as visibility into impact. I actually am supportive of a centralized discussion space for these so that web developers aren't having to ping each browser vendor. So this will result in scale of visibility through DevRel of major corps and the chrome/edge/webkit/mozilla status pages can link to that central discussion forum for deprecation impact.

There should be an agreed upon timeline with an understanding of flexibility for adjusting the timeline as new impact data is provided. Much as our pipelines have checkoffs to contribute code we should ensure that there are receipts for potential impact analysis beyond API usage from a single engine.

Like I've noted in the past, our team on Salesforce will likewise help trumpet these announcements to ensure that customers that build on our platform are informed and we can help provide insights into the potential impact on our customers.

[David Fitzgibbon]

I'm no one important at all, I'm a fairly normal dev. 

Here's a few realities of how I work that I think might be important

1. I dont have the time or interest to have to keep up to date on potential deprecations, there's enough to do with new stuff, and actually having free time.

2. My normal work day will have me in the console though, but maybe not browser X or Y. Of course I test across browsers, but I might not see the console of all browsers (I'm more front-of-the-front-end).

3. When I do hear about new functionalities, it's because there's a big fanfare about them

4. When something is added to the web platform, it is unlikely to have an effect on code I've already written

5. When something is removed from the web platform, I have no idea what effect it may have on my code, or the packages I rely on, or how much time/money it will cost me to deal with it. This is extremely worrying

Could I suggest a minimum timeframe to remove (depending on security issues of course)? EG have active warnings in the console, in all major browsers, for 12 months, before deprecation?

[Katelyn Gadd]

I think this most recent deprecation is also a case where the casual way the deprecation was handled did not match the broad impact and severity of impact for the deprecation.

For a cherry-picked comparison: People were very unhappy about the WebAudio-starts-silenced-unless-you're-google changes, but when it broke it was obvious and there was a straightforward remedy, so the severity of impact was arguably lower. The impact was also less broad since webaudio is not pervasive on the web (though I think only someone with access to telemetry from Googlebot would know how common it is).

In comparison, alert() and confirm() are likely used in 10% or more of all websites, and likely to only be used in error handler paths in some cases. These paths may be in third-party libraries so they're not under control of the site developer. It's unclear to me whether exhaustive telemetry was already used in the process of planning and rolling out this deprecation, but if you look at the breadth of the impact and the difficulty of going through and tearing modals out of *all the code touched by your website* it should easily rank as a deprecation that requires extreme caution, loud messaging, multiple stages of removal, etc. Console warnings and deprecation reports seem like a necessary first step before even thinking about actually breaking an API, especially one used so broadly.

This particular deprecation is also intermittent from the user and webdev's perspective, which is worse - a developer testing their code in a local testing environment might not get the new post-deprecation behavior because it only applied under certain circumstances, even though the goal is to eventually remove these APIs entirely. This suggests that while the deprecation was limited (to iframes, or etc) the warnings should probably be generated for *all uses* of the API so that developers know well in advance that they need to begin migrating away from the API somehow.

This all makes me long for the distant past where breaking even 0.1% of websites made my web platform colleagues wary of introducing a new JS API or fixing a bug.

[Yoav Weiss]

Hey Greg!

On Tue, Sep 14, 2021 at 5:21 PM Greg Whitworth <gkwin...@gmail.com> wrote:

This won't surprise Yoav, but I am very much in support of improving the process. One thing that I'd like to see also is coordination with other browser vendors when necessary.

That's already baked into the process, both in the form of signals from other vendors, as well as through spec changes.

Can you expand on what more is needed on that front from the Blink process perspective?

 

To view this discussion on the web visit https://groups.google.com/a/chromium.org/d/msgid/blink-api-owners-discuss/dab1a8f8-dda6-435c-beb9-c9dd30f7d195n%40chromium.org.

[Ashley Gullen]

What I find most surprising about deprecations and removals in Chrome, is they often don't seem necessary as they could have been done less disruptively. Sometimes they seem to be poorly thought out changes that are being forced through. Naturally in this case as a web developer my inclination is to resist. But it's difficult to feel heard when trying to suggest something less disruptive that still achieves the same goals; often it feels like it's too late, the decision has been made, and we're all being told to just deal with it.

The change to Web Audio is a good example. It could have been done backwards-compatibly: just mute the page on startup, and automatically unmute it on the first user input event. Legitimate content would keep working with no changes, albeit starting off muted. Abusive content still can't play audio straight away. The goal is achieved with no API changes and no need to tell the entire web to update their Web Audio code. Why did it get done in a breaking way? Did Google even consider this as an alternative? I never found out. But I do know that all our code got broken, we had to go and update everything, tell our customers to re-publish content, and then Web Audio is permanently more complicated to use for all developers in future. Without knowing why the less disruptive route wasn't taken, it's hard not to feel it was a mistake, and if anything I wish I argued against it even more forcefully than I did at the time.

Moving on to the process of removing JS dialogs, why not confine them to only appear in the frame that created them? Those frames can already show arbitrary content, including trying to misrepresent themselves. If the dialog can't escape the calling frame, it should prevent any confusion over the source of the dialog, as it is no longer possible for an iframe to display a dialog over the top frame. This would keep full API compatibility for most legitimate use cases. It might break some cases where invisible iframes expect the user to be able to dismiss a dialog. However that would be far less common, and probably include a much greater proportion of abusive use cases that we all actually want blocked. And then you wouldn't be doing things like breaking coding tutorials all over the web. Why was this approach not taken? I can't tell. Again, it just seems like a mistake, and I haven't seen anyone from Google justify why removal of a decades-old web platform feature beats changing the implementation to prevent abuse or confusion (please do correct me if someone has explained this). The impression is of Google forcing through their own decision without any scope to reconsider a better alternative, so naturally the inclination as a web developer is to resist it. Luckily Google seems to have backed down this time - maybe there is a chance it can be done differently after all - but worryingly it looks like it's only a postponement and we'll still get the same breakage in the end.

At a minimum I think Google needs to do more to communicate what alternatives were considered and why they were not chosen. If you're going to cause compatibility nightmares for web developers at Internet scale, you better have a good reason, and too often it seems like the reason isn't good enough. And consider that if you make an announcement and there's a significant backlash, perhaps it really is a mistake after all, and you should try something different.