Add CloudEvents extension for deprecated events #1307
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,86 @@ | ||
| # Deprecation extension | ||
|
|
||
| This specification defines attributes that can be included in CloudEvents to | ||
| indicate to [consumers](../spec.md#consumer) or | ||
| [intermediaries](../spec.md#intermediary) the deprecation of events. These | ||
| attributes inform CloudEvents consumers about upcoming changes or removals, | ||
| facilitating smoother transitions and proactive adjustments. | ||
|
|
||
| ## Notational Conventions | ||
|
|
||
| As with the main [CloudEvents specification](../spec.md), the key words "MUST", | ||
| "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", | ||
| "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as | ||
| described in [RFC 2119](https://tools.ietf.org/html/rfc2119). | ||
|
|
||
| However, the scope of these key words is limited to when this extension is | ||
| used. For example, an attribute being marked as "REQUIRED" does not mean it | ||
| needs to be in all CloudEvents, rather it needs to be included only when this | ||
| extension is being used. | ||
|
|
||
| ## Attributes | ||
|
|
||
| ### deprecated | ||
|
There was a problem hiding this comment. Since we basically say that even REQUIRED fields are really optional if the extension isn't used, I'm wondering if this one should be REQUIRED. It would be kind of weird to have this one "false" but any of the other attributes present, right? There was a problem hiding this comment. That's a valid point. The initial proposal had this attribute as required: but I believe that requiring this field will help to ensure clarity and prevent contradictory states. Will make the changes. |
||
|
|
||
| - Type: `Boolean` | ||
| - Description: Indicates whether the event type is deprecated. | ||
| - Constraints | ||
| - MUST be true | ||
|
|
||
| - REQUIRED | ||
| - Example: `"deprecated": true` | ||
|
|
||
| ### deprecationfrom | ||
|
|
||
| - Type: `Timestamp` | ||
| - Description: Specifies the date and time when the event type was | ||
| officially marked as deprecated. | ||
| - Constraints | ||
|
There was a problem hiding this comment. Should we have a constraint around the stability of this? (It would be odd for it to vary over time.) Should this always be in the (potentially very near) past or does it make sense to pre-announce deprecation? There was a problem hiding this comment. added a new constraint. |
||
| - OPTIONAL | ||
| - The `deprecationfrom` timestamp SHOULD remain stable once set and SHOULD | ||
|
There was a problem hiding this comment. Just curious, aside from this being a possible "FYI" bit of info, do people use this timestamp for some purpose in real life? Doesn't seem like it would influence people's action.... the "sunset" one is the important one. There was a problem hiding this comment. the There was a problem hiding this comment. In theory, but I would think the presence of any of these would indicate that the event is deprecated regardless of when the deprecation period stated, right? There was a problem hiding this comment. that's correct. |
||
| reflect a point in the past or present. Pre-announcing deprecation by | ||
| setting a future date is not encouraged. | ||
| - Example: `"deprecationfrom": "2024-10-11T00:00:00Z"` | ||
|
|
||
| ### deprecationsunset | ||
|
|
||
| - Type: `Timestamp` | ||
| - Description: Specifies the future date and time when the event type will | ||
| become unsupported. | ||
| - Constraints | ||
|
There was a problem hiding this comment. I wonder whether it's worth constraining this to say that the sunset for a type should never be observed to become earlier, but may be observed to become later. (An event producer may choose to support an event for longer than initially expected, but shouldn't shorten that support window.) There was a problem hiding this comment. added a constraint. |
||
| - OPTIONAL | ||
| - The timestamp MUST be later than or the same as the one given in the | ||
| `deprecationfrom` field, if present. It MAY be extended to a later date but | ||
| MUST NOT be shortened once set. | ||
| - Example: `"deprecationsunset": "2024-11-12T00:00:00Z"` | ||
|
|
||
| ### deprecationmigration | ||
|
|
||
| - Type: `URI` | ||
| - Description: Provides a link to documentation or resources that describe | ||
| the migration path from the deprecated event to an alternative. This helps | ||
| consumers transition away from the deprecated event. | ||
| - Constraints | ||
| - OPTIONAL | ||
| - The URI SHOULD point to a valid and accessible resource that helps | ||
| consumers understand what SHOULD replace the deprecated event. | ||
| - Example: `"deprecationmigration": "https://example.com/migrate-to-new-evt"` | ||
|
|
||
| ## Usage | ||
|
|
||
| When this extension is used, producers MUST set the value of the `deprecated` | ||
| attribute to `true`. This gives consumers a heads-up that they SHOULD begin | ||
| migrating to a new event or version. | ||
|
|
||
| Consumers SHOULD make efforts to switch to the suggested replacement before the | ||
| specified `deprecationsunset` timestamp. It is advisable to begin transitioning | ||
| as soon as the event is marked as deprecated to ensure a smooth migration and | ||
| avoid potential disruptions after the sunset date. | ||
|
|
||
| If an event is received after the `deprecationsunset` timestamp, consumers | ||
| SHOULD choose to stop processing such events, especially if unsupported events | ||
| can cause downstream issues. | ||
|
|
||
| Producers SHOULD stop emitting deprecated events after the `deprecationsunset` | ||
| timestamp. They SHOULD also provide detailed documentation via the | ||
| `deprecationmigration` attribute to guide consumers toward the correct replacement | ||
| event. | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,2 @@ | ||
| # Deprecation extension | ||
| מסמך זה טרם תורגם. בבקשה תשתמשו [בגרסה האנגלית של המסמך](../../../extensions/deprecation.md) לבינתיים. |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,6 @@ | ||
| # Deprecation extension | ||
|
|
||
| 本文档尚未被翻译，请先阅读英文[原版文档](../../../extensions/deprecation.md) 。 | ||
|
|
||
| 如果您迫切地需要此文档的中文翻译，请[提交一个issue](https://github.com/cloudevents/spec/issues) ， | ||
| 我们会尽快安排专人进行翻译。 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'd like some sort of attribute describing a migration path - "stop using this, start using X". We could make that a URI instead of text, for people to link to docs. Not sure of the details, but something would be good.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Added a new (optional) attribute:
deprecationmigration