I would add a warning based on my experience with trying to deprecateUIEvent's layerX / layerY: your proposal seems to be to just go ahead
and deprecate some API while counting usage at the same time. Unless
you want to get developers' wrath on bugs or this mailing list, you
should probably first measure the use and then do the deprecation (ie
split the 2 steps). Making assumption about the brokenness of an API
from Blink code's point of view doesn't really translate to real-world
use.
Also does [DeprecateAs] only dumps once per page or is it for each use
of the deprecated API?
How to Deprecate/Remove a Web Platform Feature
- Carefully consider whether you can jump straight to deprecation without first measuring the feature's usage in the wild.
- If you'd rather measure first:
- Add your feature to the UseCounter::Feature enum.
- Add
MeasureAs=[your enum value here]
to the feature's IDL definition.*- Email blink-dev using the "Intent to Deprecate" template when you're ready.
- Measure usage and notify developers.
- If you haven't, add it to the UseCounter::Feature enum.
- Instrument your code by either:
- Adding
DeprecateAs=[your enum value here]
to the feature's IDL definition.*^ Seewindow.performance.webkitGetEntries
, for example.
- Adding a call to
UseCounter::countDeprecation
somewhere relevant (as we're dong for the prefixed Content Security Policy headers).
- Notify developers by adding a clever deprecation message to the big switch in UseCounter::deprecationMessage. This will print a deprecation warning in the DevTools console.
- Note: it takes 12-18 weeks to hit Stable once you enable instrumentation.
- Email blink-dev using the "Intent to Remove" template when you're ready. Wait for LGTMs from ≥3 API OWNERS.
- Remove.
* It takes 12-18 weeks to hit Stable once you enable instrumentation.^DeprecateAs
is intended to replaceMeasureAs
in the IDL file. Specifying both is redundant.
My original intention was to have deprecations and feature removals go through the ordinary launch process, but after reading this thread I think it might be better to define distinct paths for new features vs deprecations. How does this sound:How to Deprecate/Remove a Web Platform Feature
- Carefully consider whether you can jump straight to deprecation without first measuring the feature's usage in the wild.
- If you'd rather measure first:
- Add your feature to the UseCounter::Feature enum.
- Add
MeasureAs=[your enum value here]
to the feature's IDL definition.*
On Fri, Apr 26, 2013 at 4:00 PM, Max Heinritz <m...@chromium.org> wrote:
My original intention was to have deprecations and feature removals go through the ordinary launch process, but after reading this thread I think it might be better to define distinct paths for new features vs deprecations. How does this sound:How to Deprecate/Remove a Web Platform Feature
- Carefully consider whether you can jump straight to deprecation without first measuring the feature's usage in the wild.
- If you'd rather measure first:
- Add your feature to the UseCounter::Feature enum.
- Add
MeasureAs=[your enum value here]
to the feature's IDL definition.*It's not obvious (maybe it's just me), what are the criteria for measuring and not measuring the usage before proceeding further.I think it would be useful to have some examples of when it is necessary to measure the usage, and a few examples of when it is not needed.
Decide if your feature needs to go through this process.
- You can skip 2-5 if you’re removing a trivial feature (e.g. a quirk that is exclusive to WebKit, like RangeException).
- Canary, Dev, and Beta users will complain if it breaks the web. But if your reviewer suggests going through the rest of this process, do it.
Carefully consider whether you can jump straight to deprecation without first measuring the feature's usage in the wild.
- If you're sure you're not going to cause compatibility problems, then you don't need to measure. If you're unsure, then measuring is probably a good idea.
- If you'd rather measure first:
- Add your feature to the UseCounter::Feature enum.
- Add MeasureAs=[your enum value here] to the feature's IDL definition.*
Email blink-dev using the "Intent to Deprecate" template.
Deprecate: notify developers and measure usage.
- If you haven't, add your feature to the UseCounter::Feature enum.
- Instrument your code by either:
- Adding DeprecateAs=[your enum value here] to the feature's IDL definition.*^ See window.performance.webkitGetEntries, for example.
- Adding a call to UseCounter::countDeprecation somewhere relevant (as we did for the prefixed Content Security Policy headers).
- Notify developers by adding a clever deprecation message to the big switch in UseCounter::deprecationMessage. This will print a deprecation warning in the DevTools console.
Email blink-dev using the "Intent to Remove" template. Wait for LGTMs from ≥3 API OWNERS.
Remove.
^ DeprecateAs is intended to replace MeasureAs in the IDL file. Specifying both is redundant.
* It takes 12-18 weeks to hit Stable once you enable instrumentation.
See this blink-dev thread for more information on deprecation.