Taking our API deprecation warnings more seriously

[Rick Byers]

If you don't care about the process for deprecating web-exposed APIs you can stop reading now.

We've got a lot of APIs in the web platform that we'd all love to remove someday.  Unfortunately, being good stewards of a long-lasting platform means we have to be very thoughtful about how we do that without damaging developer confidence and the user experience.

We've had a couple examples recently where (despite very low usage) we felt it was probably a mistake to have removed an API without a deprecation period.  In the future I feel we should hold ourselves to a slightly higher bar - almost always giving developers at least one milestone of warning before removing an API with non-zero usage.  We're also exploring other ideas for better communicating API deprecation to web developers (the devtools console alone is a very leaky feedback channel).

If we'd like web developers to take our deprecation warnings seriously we also need to avoid over-using them.  We have a few examples of long-standing deprecation warnings with no credible plan for removal in any concrete time frame.  Going forward I propose that all "intent to deprecate" threads should include a concrete plan for removal in a specific milestone, and that the deprecation warnings should include the removal milestone (a pattern that most new warnings have already been following).  We know that merely listing an API as deprecated does not have much impact on usage in practice, so it's not enough to hope that deprecating an API will result in the usage dropping below a level that we can break in the future.

Some of the API owners chatted about this today and there was general agreement, and so I've optimistically tweaked the deprecation process and template.  If there's consensus then I will begin to file bugs for the people who have added existing deprecation messages that don't already include a removal milestone (though I'm in no specific rush to see all messages updated or removed).  In the future I could imagine us building some tooling to help encourage and automate this process.

Thoughts?

   Rick

[Joe Medley]

On Tue, Dec 8, 2015 at 12:34 PM, Rick Byers <rby...@chromium.org> wrote:

Going forward I propose that all "intent to deprecate" threads should include a concrete plan for removal in a specific milestone, and that the deprecation warnings should include the removal milestone (a pattern that most new warnings have already been following). 

Three cheers to that. If I know when it's being deprecated and removed I can document it and developers can have another way of learning that something is going away.

Joe Medley | Technical Writer, DevPlat | jme...@google.com | 816-678-7195

[Philip Jägenstedt]

Awesome! Do you also think we should document how to determine the approximate date that the milestone will be released? My method has been to add 50 days to the branch date, and stating it as "around April 2016" or similar. Is that good enough? We should err towards earlier dates so that developers don't get less time than stated.

Here are the currently deprecated things sorted by usage, with quite a few things not ready for removal:

• XMLHttpRequestSynchronousInNonWorkerOutsideBeforeUnload 1.4242%
  
• SVGSMILElementInDocument 0.4608%
  
• PrefixedIndexedDB 0.3291%
  
• PrefixedMouseEventMovementX 0.1931%
  
• PrefixedMouseEventMovementY 0.1930%
  
• DeviceOrientationInsecureOrigin 0.1485%
  
• KeyboardEventKeyLocation 0.1087%
  
• PrefixedWindowURL 0.0925%
  
• PrefixedPerformanceClearResourceTimings 0.0864%
  
• PrefixedAudioContext 0.0738%
  
• PrefixedStorageInfo 0.0712%
  
• PrefixedRequestAnimationFrame 0.0693%
  
• MediaStreamTrackGetSources 0.0627%
  
• CSSDeepCombinator 0.0592%
  
• SVGSMILAnimationInImageRegardlessOfCache 0.0521%
  
• RangeDetach 0.0448%
  
• SyncXHRWithCredentials 0.0439%
  
• V8SVGElement_OffsetHeight_AttributeGetter 0.0393%
  
• V8SVGElement_OffsetWidth_AttributeGetter 0.0390%
  
• GetMatchedCSSRules 0.0340%
  
• GeolocationInsecureOrigin 0.0296%
  
• DeviceMotionInsecureOrigin 0.0224%
  
• CSSSelectorPseudoShadow 0.0167%
  
• PrefixedPerformanceSetResourceTimingBufferSize 0.0160%
  
• PrefixedPerformanceResourceTimingBufferFull 0.0138%
  
• CSSStyleSheetInsertRuleOptionalArg 0.0100%
  
• PrefixedImageSmoothingEnabled 0.0086%
  
• PrefixedCancelAnimationFrame 0.0083%
  
• PrefixedVideoDisplayingFullscreen 0.0069%
  
• EncryptedMediaInsecureOrigin 0.0067%
  
• XHRProgressEventPosition 0.0063%
  
• PrefixedIDBTransactionConstructor 0.0048%
  
• PrefixedIDBKeyRangeConstructor 0.0048%
  
• ElementCreateShadowRootMultiple 0.0047%
  
• PrefixedOfflineAudioContext 0.0046%
  
• V8SVGElement_OffsetTop_AttributeGetter 0.0043%
  
• V8SVGElement_OffsetLeft_AttributeGetter 0.0043%
  
• PrefixedIDBRequestConstructor 0.0042%
  
• PrefixedIDBFactoryConstructor 0.0042%
  
• PrefixedIDBDatabaseConstructor 0.0042%
  
• PrefixedIDBCursorConstructor 0.0042%
  
• PrefixedIDBObjectStoreConstructor 0.0040%
  
• PrefixedIDBIndexConstructor 0.0040%
  
• XHRProgressEventTotalSize 0.0039%
  
• PrefixedCancelRequestAnimationFrame 0.0037%
  
• SVGSVGElementUnsuspendRedraw 0.0033%
  
• SVGSVGElementSuspendRedraw 0.0033%
  
• ConsoleTimeline 0.0025%
  
• V8SVGElement_OffsetParent_AttributeGetter 0.0018%
  
• PrefixedVideoExitFullScreen 0.0011%
  
• ConsoleTimelineEnd 0.0011%
  
• PrefixedVideoSupportsFullscreen 0.0008%
  
• GetUserMediaInsecureOrigin 0.0008%
  
• PrefixedVideoEnterFullScreen 0.0007%
  
• PrefixedVideoExitFullscreen 0.0006%
  
• PictureSourceSrc 0.0006%
  
• AudioListenerDopplerFactor 0.0005%
  
• AudioListenerSpeedOfSound 0.0003%
  
• PrefixedVideoEnterFullscreen 0.0002%
  
• ConsoleMarkTimeline 0.0002%
  
• RangeExpand 0.0001%
  
• FileError 0.0001%
  
• SVGSVGElementUnsuspendRedrawAll 0.0000%
  
• SVGSVGElementForceRedraw 0.0000%
  
• PrefixedMediaGenerateKeyRequest 0.0000%
  
• PrefixedMediaCancelKeyRequest 0.0000%
  
• PrefixedMediaAddKey 0.0000%
  
• NodeIteratorDetach 0.0000%
  
• ElementCreateShadowRootMultipleWithUserAgentShadowRoot 0.0000%
  
• CanPlayTypeKeySystem 0.0000%
  
• AudioListenerSetVelocity 0.0000%
  

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

[Rick Byers]

On Wed, Dec 9, 2015 at 10:27 AM, Philip Jägenstedt <phi...@opera.com> wrote:

Awesome! Do you also think we should document how to determine the approximate date that the milestone will be released? My method has been to add 50 days to the branch date, and stating it as "around April 2016" or similar. Is that good enough? We should err towards earlier dates so that developers don't get less time than stated.

 Something approximate like this seems fine.  Though I think 50 days is too long - eg. the calendar gives us about 45 days from branch to approximate stable for M49.  I think we often use "around 6 weeks" (42 days) as a rough rule of thumb (though of course lots of things can change it).

Here are the currently deprecated things sorted by usage, with quite a few things not ready for removal:

Thanks.  Of course the usage alone isn't enough to make this decision.  Eg. we know the event properties like webkitMovementX/Y are a vast over-estimate (due to the prevalence of event-copying code). 

• XMLHttpRequestSynchronousInNonWokerOutsideBeforeUnload 1.4242%
  

[Sigbjorn Finne]

Den 12/9/2015 16:38, Rick Byers skreiv:
> On Wed, Dec 9, 2015 at 10:27 AM, Philip Jägenstedt <phi...@opera.com

> <mailto:phi...@opera.com>> wrote:
>
....

>
> Here are the currently deprecated things sorted by usage, with quite
> a few things not ready for removal:
>
>
> Thanks. Of course the usage alone isn't enough to make this decision.
> Eg. we know the event properties like webkitMovementX/Y are a vast
> over-estimate (due to the prevalence of event-copying code).
>

> * XMLHttpRequestSynchronousInNonWokerOutsideBeforeUnload 1.4242%

Given https://crbug.com/513059 , is it reasonable to assume that this &
other numbers here are higher by some amount? Or generally trust
renderer UMA numbers?

( Sorry to go off on a tangent, just bothered with the apparent
imprecision. )

--sigbjorn

[Rick Byers]

I agree fixing that bug is super important.  But given that we seem to have been able to make reasonable / successful deprecation decisions in the past based on this data, we'be been assuming that it's still at least somewhat representative.  I'm not aware of anyone trying to test that hypothesis though, it's certainly possible that this bug introduces a significant bias to the data that invalidates our decision making...

 

--sigbjorn

[Philip Jägenstedt]

On Wed, Dec 9, 2015 at 4:38 PM, Rick Byers <rby...@chromium.org> wrote:

On Wed, Dec 9, 2015 at 10:27 AM, Philip Jägenstedt <phi...@opera.com> wrote:

Awesome! Do you also think we should document how to determine the approximate date that the milestone will be released? My method has been to add 50 days to the branch date, and stating it as "around April 2016" or similar. Is that good enough? We should err towards earlier dates so that developers don't get less time than stated.

 Something approximate like this seems fine.  Though I think 50 days is too long - eg. the calendar gives us about 45 days from branch to approximate stable for M49.  I think we often use "around 6 weeks" (42 days) as a rough rule of thumb (though of course lots of things can change it).

Oh,I haven't seen the Estimated Stable Dates section before. When I came up with the 50 days estimate, that was the fastest time for releases M32-M41. Here are the releases since:

M42: Feb 20, 2015 => Apr 14, 2015 (53 days)
M43: Apr 3, 2015 => May 19, 2015 (46 days)
M44: May 15, 2015 => Jul 21, 2015 (67 days)
M45: Jul 10, 2015 => Sep 1, 2015 (53 days)
M46: Aug 21, 2015 => Oct 13, 2015 (53 days)
M47: Oct 2, 2015 => Dec 1, 2015 (60 days)

So with 46 days as the new fastest time, I think "around 6 weeks" will work fine.