Report body: disambiguate deprecation timelines

[maudnals]

One key information developers need from deprecation reports is whether an API is already deprecated or whether it will be deprecated. Depending on this information, developers will approach the issue differently.

• Developers will typically want to handle/migrate already-deprecated API calls with more urgency.
• Developers would likely want to translate will-be-deprecated API calls into a new backlog item, to look into migration strategies⏤and this item's priority will depend on the planned deprecation date.

Assumptions

• Whether an API is already deprecated or whether it will be deprecated is important information for developers.
• The UA info in the request sent by the browser is sufficient for devs to know "In what browser is this API deprecated". (see https://github.com/w3c/reporting/issues/246)
• "past" and "present" should be seen relatively from the perspective of the UA in which the deprecation was called. For example, assuming we're at a point in time where the latest Chrome version is Chrome 96. A report generated in Chrome 94 by a user who hasn't updated their Chrome version should say "API x will be deprecated by Chrome 95" but a deprecation report generated in Chrome 96 should say "API X was deprecated in Chrome 95". The information contained in the UA can be used to complete the picture and know "how old is the browser that emitted this report".

Problem today 💥

Today, by looking at a deprecation report, there's no straightforward way to know whether an API is deprecated or will be deprecated. The optional field anticipatedRemoval isn't sufficient because:

• Even when it's present, the endpoint needs to parse it, then parse the UA-string (that's another issue, see https://github.com/w3c/reporting/issues/246), and then from that deduce whether or not the API is deprecated in the UA that generated the report.
• When it's absent, it may either mean two very different things:
  • The deprecation date is unknown, which may mean that the deprecation will not happen
  • OR that the deprecation has taken place already

Source: https://wicg.github.io/deprecation-reporting/#deprecation-report

anticipatedRemoval: A JavaScript Date object (rendered as an ISO 8601 string) indicating roughly when the browser version without the specified API will be generally available (excluding "beta" or other pre-release channels). This value should be used to sort or prioritize warnings. If unknown, this field should be null, and the deprecation should be considered low priority (removal may not actually occur).

Proposed solution ☑️

Extend the report body with two new fields:

• deprecated: true | false
• removedSince: only present if deprecated is true

anticipatedRemoval remains, but can be present only if deprecated is false. If deprecated is false and anticipatedRemoval is absent, it means, like in today's spec, that the removal may not actually occur.

⁉️ Open question: Should the dates in removedSince and anticipatedRemoval be actual human readable dates? Or should they be browser versions?

[maudnals]

Developer journey with the proposed solution 👩🏻‍💻

"Alice" = developer

• Alice receives a deprecation report on the collector system her team's set up. Report info says it was generated from UA=Chrome Version=95.
• Alice checks the report's (new) deprecated field:
  • If true: this API is already deprecated. this likely means Alice needs to migrate. She may check the value of removedSince: typically, the older removedSince is, the higher the prio of this migration.
  • If false: this API isn't yet deprecated according to that UA.
    • Alice checks anticipatedRemoval.
    • If anticipatedRemoval is absent:
      • Alice checks the UA version.
      • If the UA is in its latest version, no defined anticipatedRemoval means that the API may or may not be deprecated in the future. Alice knows she needs look into migration strategies⏤very low prio if this API isn't key to Alice's web app, higher prio in case the web app's core use case does rely on this API.
      • If the UA is old, no action for Alice. In case has been decided in newer UAs to actually set an anticipatedRemoval date for this deprecation, Alice will be notified of this in other reports, coming from users of newer UAs. So nothing falls through the cracks.
    • If anticipatedRemoval is present: Alice checks its value.
      • If the value is in the future, it means the API will be deprecated in the future. Depending on how soon this is, and how critical this API is for Alice's team, Alice creates a low- to high-prio migration action item.
      • If the value is in the past, it means that this report was generated from a user of an old UA. => The API is already deprecated in newers UAs. Alice should be notified of this in other reports, coming from users of newer UAs.

[agektmr]

Bump. I consider deprecation reports is one of key pieces to help developers catching up with the current rapid evolution. How can we get this sorted?