More discussion around possible process improvements for deprecations

[Chris Harrelson]

Following up on the recent alert-in-iframes intent, the API owners had a discussion about possible ways to improve.

I recall the following possible changes being raised:

1. A requirement to publish public clear documentation of the deprecation and intent to remove in a blog, such as a web.dev post

2. Require lockstep on changes with other browsers

3. Require positive developer signals supporting the removal

4. Require enterprise outreach

There was pushback on requiring any of them, and I agree with this pushback. The reason is that in some cases (example), the deprecation is indeed simple, uncontroversial and/or obscure enough that it requires too much work to do all those things relative to the actual risk. And if we require them, then Chromium developers will react by simply not deprecating anything, which would be bad.

There are clearly cases where each of the enumerated items above would be necessary, but I can't come up with a hard and fast rule for any of them.

One thing we can do right away is improve the instructions and templates for deprecations to make it easier to find best practices. There is also at least one Google-internal doc, that we should make a public version of, that has some good tips and tricks. +Shruthi Sreekanta kindly agreed to help with that.

How about this as well: we require a new section that links to the documentation of the kinds of problems which may occur and suggested actions to mitigate them, and asks the intent owner "Please read this list of risk factors and mitigations. Do any of them apply in this situation? If so, which? Please link to artifacts attesting to the action you've taken along those lines." or similar text.

WDYT?

Chris

[Shruthi Sreekanta]

On Fri, Sep 24, 2021 at 5:04 PM Chris Harrelson <chri...@chromium.org> wrote:

Following up on the recent alert-in-iframes intent, the API owners had a discussion about possible ways to improve.

I recall the following possible changes being raised:

1. A requirement to publish public clear documentation of the deprecation and intent to remove in a blog, such as a web.dev post

2. Require lockstep on changes with other browsers

3. Require positive developer signals supporting the removal

4. Require enterprise outreach

There was pushback on requiring any of them, and I agree with this pushback.

The reason is that in some cases (example), the deprecation is indeed simple, uncontroversial and/or obscure enough that it requires too much work to do all those things relative to the actual risk. And if we require them, then Chromium developers will react by simply not deprecating anything, which would be bad.

There are clearly cases where each of the enumerated items above would be necessary, but I can't come up with a hard and fast rule for any of them.

Especially the two around lockstep with other browsers and positive developer signals might be really hard as absolute requirements for most deprecations. However, we don't need them to be hard and fast rules, in my opinion, for them to have an impact on how we deprecate. If the API Owners believe these are the specific gaps in the deprecation process, we could add the questions/guidance to the intent template. That way, teams are prompted to think about these and the API Owners have the additional information they need to make the right decision. 

One thing we can do right away is improve the instructions and templates for deprecations to make it easier to find best practices. There is also at least one Google-internal doc, that we should make a public version of, that has some good tips and tricks. +Shruthi Sreekanta kindly agreed to help with that.

Specifically, the documentation we discussed was this one: Enterprise-friendly changes. It is now linked off of the Blink launch documentation on deprecations. If I find any other relevant, Google-internal ones, I will be sure to make them public and add links to the launch documentation.

[Jason Chase]

On Mon, 27 Sept 2021 at 18:03, 'Shruthi Sreekanta' via blink-api-owners-discuss <blink-api-ow...@chromium.org> wrote:

On Fri, Sep 24, 2021 at 5:04 PM Chris Harrelson <chri...@chromium.org> wrote:

Following up on the recent alert-in-iframes intent, the API owners had a discussion about possible ways to improve.

I recall the following possible changes being raised:

1. A requirement to publish public clear documentation of the deprecation and intent to remove in a blog, such as a web.dev post

2. Require lockstep on changes with other browsers

3. Require positive developer signals supporting the removal

4. Require enterprise outreach

There was pushback on requiring any of them, and I agree with this pushback.

The reason is that in some cases (example), the deprecation is indeed simple, uncontroversial and/or obscure enough that it requires too much work to do all those things relative to the actual risk. And if we require them, then Chromium developers will react by simply not deprecating anything, which would be bad.

There are clearly cases where each of the enumerated items above would be necessary, but I can't come up with a hard and fast rule for any of them.

Especially the two around lockstep with other browsers and positive developer signals might be really hard as absolute requirements for most deprecations. However, we don't need them to be hard and fast rules, in my opinion, for them to have an impact on how we deprecate. If the API Owners believe these are the specific gaps in the deprecation process, we could add the questions/guidance to the intent template. That way, teams are prompted to think about these and the API Owners have the additional information they need to make the right decision. 

One thing we can do right away is improve the instructions and templates for deprecations to make it easier to find best practices. There is also at least one Google-internal doc, that we should make a public version of, that has some good tips and tricks. +Shruthi Sreekanta kindly agreed to help with that.

Specifically, the documentation we discussed was this one: Enterprise-friendly changes. It is now linked off of the Blink launch documentation on deprecations. If I find any other relevant, Google-internal ones, I will be sure to make them public and add links to the launch documentation.

Another good doc is High-Usage API Deprecation (already public). This is Mason Freed's writeup of the learnings from the Web Components V0 deprecation.

 

How about this as well: we require a new section that links to the documentation of the kinds of problems which may occur and suggested actions to mitigate them, and asks the intent owner "Please read this list of risk factors and mitigations. Do any of them apply in this situation? If so, which? Please link to artifacts attesting to the action you've taken along those lines." or similar text.

WDYT?

Chris

--
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/CAAccXerej92F%3DuE-YtG6dgoWn6PasGx%3De09sAK6CD%3D8wsLV50A%40mail.gmail.com.

[Chris Harrelson]

On Mon, Sep 27, 2021 at 3:40 PM Jason Chase <cha...@chromium.org> wrote:

On Mon, 27 Sept 2021 at 18:03, 'Shruthi Sreekanta' via blink-api-owners-discuss <blink-api-ow...@chromium.org> wrote:

On Fri, Sep 24, 2021 at 5:04 PM Chris Harrelson <chri...@chromium.org> wrote:

Following up on the recent alert-in-iframes intent, the API owners had a discussion about possible ways to improve.

I recall the following possible changes being raised:

1. A requirement to publish public clear documentation of the deprecation and intent to remove in a blog, such as a web.dev post

2. Require lockstep on changes with other browsers

3. Require positive developer signals supporting the removal

4. Require enterprise outreach

There was pushback on requiring any of them, and I agree with this pushback.

The reason is that in some cases (example), the deprecation is indeed simple, uncontroversial and/or obscure enough that it requires too much work to do all those things relative to the actual risk. And if we require them, then Chromium developers will react by simply not deprecating anything, which would be bad.

There are clearly cases where each of the enumerated items above would be necessary, but I can't come up with a hard and fast rule for any of them.

Especially the two around lockstep with other browsers and positive developer signals might be really hard as absolute requirements for most deprecations. However, we don't need them to be hard and fast rules, in my opinion, for them to have an impact on how we deprecate. If the API Owners believe these are the specific gaps in the deprecation process, we could add the questions/guidance to the intent template. That way, teams are prompted to think about these and the API Owners have the additional information they need to make the right decision. 

One thing we can do right away is improve the instructions and templates for deprecations to make it easier to find best practices. There is also at least one Google-internal doc, that we should make a public version of, that has some good tips and tricks. +Shruthi Sreekanta kindly agreed to help with that.

Specifically, the documentation we discussed was this one: Enterprise-friendly changes. It is now linked off of the Blink launch documentation on deprecations. If I find any other relevant, Google-internal ones, I will be sure to make them public and add links to the launch documentation.

Another good doc is High-Usage API Deprecation (already public). This is Mason Freed's writeup of the learnings from the Web Components V0 deprecation.

Great example! I added a link to it here. 

[Yoav Weiss]

I agree that (2) and (3) may be hard to achieve in all cases. (1) and (4) seem like reasonable requirements, at least in cases with non-trivial usage and/or reasons to believe enterprise usage is under-represented in our metrics.

I'd also like to add the use of DeprecationReports (whenever possible) to give enterprises that don't want to expose usage stats a way to monitor upcoming changes on their own.

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

[Chris Harrelson]

On Wed, Sep 29, 2021 at 4:46 AM Yoav Weiss <yoav...@google.com> wrote:

I agree that (2) and (3) may be hard to achieve in all cases. (1) and (4) seem like reasonable requirements, at least in cases with non-trivial usage and/or reasons to believe enterprise usage is under-represented in our metrics.

Agreed, but the key is that it's only sometimes that they would be needed.

One thing we could do is provide each of these items to the intent owner as a yes/no question that they should fill out.

 

I'd also like to add the use of DeprecationReports (whenever possible) to give enterprises that don't want to expose usage stats a way to monitor upcoming changes on their own.

Is this easy to do? If it is, maybe we could make it a requirement.

Also: I think we should probably require that all deprecations make it into the enterprise release notes, regardless of how small. And we can make that easy by just asking the intent owner to file an issue at the right place, which would trigger this process.

[Yoav Weiss]

On Thu, Sep 30, 2021 at 6:36 PM Chris Harrelson <chri...@chromium.org> wrote:

On Wed, Sep 29, 2021 at 4:46 AM Yoav Weiss <yoav...@google.com> wrote:

I agree that (2) and (3) may be hard to achieve in all cases. (1) and (4) seem like reasonable requirements, at least in cases with non-trivial usage and/or reasons to believe enterprise usage is under-represented in our metrics.

Agreed, but the key is that it's only sometimes that they would be needed.

One thing we could do is provide each of these items to the intent owner as a yes/no question that they should fill out.

 

I'd also like to add the use of DeprecationReports (whenever possible) to give enterprises that don't want to expose usage stats a way to monitor upcoming changes on their own.

Is this easy to do? If it is, maybe we could make it a requirement.

It's easy to do for blink-based features and harder to do for e.g. network stack features. 

Also: I think we should probably require that all deprecations make it into the enterprise release notes, regardless of how small. And we can make that easy by just asking the intent owner to file an issue at the right place, which would trigger this process.

Makes sense.

[Chris Harrelson]

On Thu, Sep 30, 2021 at 9:43 AM Yoav Weiss <yoav...@google.com> wrote:

On Thu, Sep 30, 2021 at 6:36 PM Chris Harrelson <chri...@chromium.org> wrote:

On Wed, Sep 29, 2021 at 4:46 AM Yoav Weiss <yoav...@google.com> wrote:

I agree that (2) and (3) may be hard to achieve in all cases. (1) and (4) seem like reasonable requirements, at least in cases with non-trivial usage and/or reasons to believe enterprise usage is under-represented in our metrics.

Agreed, but the key is that it's only sometimes that they would be needed.

One thing we could do is provide each of these items to the intent owner as a yes/no question that they should fill out.

 

I'd also like to add the use of DeprecationReports (whenever possible) to give enterprises that don't want to expose usage stats a way to monitor upcoming changes on their own.

Is this easy to do? If it is, maybe we could make it a requirement.

It's easy to do for blink-based features and harder to do for e.g. network stack features. 

Is it a simple CL then? Can you link an example?

[Jason Chase]

On Thu, 30 Sept 2021 at 12:59, Chris Harrelson <chri...@chromium.org> wrote:

On Thu, Sep 30, 2021 at 9:43 AM Yoav Weiss <yoav...@google.com> wrote:

On Thu, Sep 30, 2021 at 6:36 PM Chris Harrelson <chri...@chromium.org> wrote:

On Wed, Sep 29, 2021 at 4:46 AM Yoav Weiss <yoav...@google.com> wrote:

I agree that (2) and (3) may be hard to achieve in all cases. (1) and (4) seem like reasonable requirements, at least in cases with non-trivial usage and/or reasons to believe enterprise usage is under-represented in our metrics.

Agreed, but the key is that it's only sometimes that they would be needed.

One thing we could do is provide each of these items to the intent owner as a yes/no question that they should fill out.

 

I'd also like to add the use of DeprecationReports (whenever possible) to give enterprises that don't want to expose usage stats a way to monitor upcoming changes on their own.

Is this easy to do? If it is, maybe we could make it a requirement.

It's easy to do for blink-based features and harder to do for e.g. network stack features. 

It's worth logging an issue to make it easier for non-blink features. Do you have an example where it was harder? I could write something up.

Is it a simple CL then? Can you link an example?

Should be pretty straightforward. Here's a recent example: https://chromium-review.googlesource.com/c/chromium/src/+/3169471 

[Ian Clelland]

On Thu, Sep 30, 2021 at 1:42 PM Jason Chase <cha...@chromium.org> wrote:

On Thu, 30 Sept 2021 at 12:59, Chris Harrelson <chri...@chromium.org> wrote:

On Thu, Sep 30, 2021 at 9:43 AM Yoav Weiss <yoav...@google.com> wrote:

On Thu, Sep 30, 2021 at 6:36 PM Chris Harrelson <chri...@chromium.org> wrote:

On Wed, Sep 29, 2021 at 4:46 AM Yoav Weiss <yoav...@google.com> wrote:

I agree that (2) and (3) may be hard to achieve in all cases. (1) and (4) seem like reasonable requirements, at least in cases with non-trivial usage and/or reasons to believe enterprise usage is under-represented in our metrics.

Agreed, but the key is that it's only sometimes that they would be needed.

One thing we could do is provide each of these items to the intent owner as a yes/no question that they should fill out.

 

I'd also like to add the use of DeprecationReports (whenever possible) to give enterprises that don't want to expose usage stats a way to monitor upcoming changes on their own.

Is this easy to do? If it is, maybe we could make it a requirement.

It's easy to do for blink-based features and harder to do for e.g. network stack features. 

It's worth logging an issue to make it easier for non-blink features. Do you have an example where it was harder? I could write something up.

This recent discussion on blink-dev went into some of the reasons that a purely network-based feature would find it hard to use the centralized deprecation.cc logic. Since UMA is handled in the browser these days, we could move the deprecation definitions somewhere that would be usable by any process, and provide an equivalent to CountDeprecation in the content layer.

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

[Chris Harrelson]

Reviving this thread.

WDYT about adding a question of this form:

If your feature is not deprecating and removing a feature, or changing its behavior, you can skip this question.

Please read this list <link to the kinds of documents and use cases referred to in this email thread> of risk factors and mitigations.

Do any of them apply in this situation? If so, which? Please link to artifacts attesting to the action you've taken along those lines.

[Yoav Weiss]

On Wed, Apr 20, 2022 at 9:59 PM Chris Harrelson <chri...@chromium.org> wrote:

Reviving this thread.

WDYT about adding a question of this form:

If your feature is not deprecating and removing a feature, or changing its behavior, you can skip this question.

Please read this list <link to the kinds of documents and use cases referred to in this email thread> of risk factors and mitigations.

Do any of them apply in this situation? If so, which? Please link to artifacts attesting to the action you've taken along those lines.

I suspect that such a question will not trigger the effect we want. We'd be asking feature developers to read through multiple documents and extrapolate parallels between them and their features.

I think it can be more useful if we were to extract the direct questions we want them to ask themselves. For example, a not-necessarily-complete list may be:

• Is current usage low?
• Is current usage declining?
• Have you done outreach to ensure developers move away from the feature you're trying to deprecate and remove? Do you have a public plan?
• Would a deprecation trial be a helpful tool to buy folks more time when migrating off the feature? Do you have an Enterprise Policy in place?
• Are you issuing deprecation reports?
• Have you notified other Chromium embedders?

We can and should link to the docs, but probably want to make the exact questions we want answered explicit.

[Chris Harrelson]

On Thu, Apr 21, 2022 at 4:55 AM Yoav Weiss <yoav...@google.com> wrote:

On Wed, Apr 20, 2022 at 9:59 PM Chris Harrelson <chri...@chromium.org> wrote:

Reviving this thread.

WDYT about adding a question of this form:

If your feature is not deprecating and removing a feature, or changing its behavior, you can skip this question.

Please read this list <link to the kinds of documents and use cases referred to in this email thread> of risk factors and mitigations.

Do any of them apply in this situation? If so, which? Please link to artifacts attesting to the action you've taken along those lines.

I suspect that such a question will not trigger the effect we want. We'd be asking feature developers to read through multiple documents and extrapolate parallels between them and their features.

I think it can be more useful if we were to extract the direct questions we want them to ask themselves. For example, a not-necessarily-complete list may be:

• Is current usage low?
• Is current usage declining?
• Have you done outreach to ensure developers move away from the feature you're trying to deprecate and remove? Do you have a public plan?
• Would a deprecation trial be a helpful tool to buy folks more time when migrating off the feature? Do you have an Enterprise Policy in place?
• Are you issuing deprecation reports?
• Have you notified other Chromium embedders?

We can and should link to the docs, but probably want to make the exact questions we want answered explicit.

That's a long list of questions, long enough that we'll have to put it into another linked document. At which point aren't these just additional examples of the "list of risk factors and mitigations"? Another way we could phrase it is as "please read through the questions in <this document> and see if any apply to your intent. If they do, then please indicate which, and your plan to mitigate them". 

[Yoav Weiss]

On Thu, Apr 21, 2022 at 6:25 PM Chris Harrelson <chri...@chromium.org> wrote:

On Thu, Apr 21, 2022 at 4:55 AM Yoav Weiss <yoav...@google.com> wrote:

On Wed, Apr 20, 2022 at 9:59 PM Chris Harrelson <chri...@chromium.org> wrote:

Reviving this thread.

WDYT about adding a question of this form:

If your feature is not deprecating and removing a feature, or changing its behavior, you can skip this question.

Please read this list <link to the kinds of documents and use cases referred to in this email thread> of risk factors and mitigations.

Do any of them apply in this situation? If so, which? Please link to artifacts attesting to the action you've taken along those lines.

I suspect that such a question will not trigger the effect we want. We'd be asking feature developers to read through multiple documents and extrapolate parallels between them and their features.

I think it can be more useful if we were to extract the direct questions we want them to ask themselves. For example, a not-necessarily-complete list may be:

• Is current usage low?
• Is current usage declining?
• Have you done outreach to ensure developers move away from the feature you're trying to deprecate and remove? Do you have a public plan?
• Would a deprecation trial be a helpful tool to buy folks more time when migrating off the feature? Do you have an Enterprise Policy in place?
• Are you issuing deprecation reports?
• Have you notified other Chromium embedders?

We can and should link to the docs, but probably want to make the exact questions we want answered explicit.

That's a long list of questions, long enough that we'll have to put it into another linked document. At which point aren't these just additional examples of the "list of risk factors and mitigations"? Another way we could phrase it is as "please read through the questions in <this document> and see if any apply to your intent. If they do, then please indicate which, and your plan to mitigate them". 

Yeah, linking to a separate doc with explicit questions makes sense to me.