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,58 @@ | ||
| # Deprecation and Sunset 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 and sunset status of | ||
| the event type. These attributes inform consumers of CloudEvents 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 | ||
|
|
||
| ### deprecation | ||
|
|
||
| - Type: `String` | ||
| - Description: Indicates that the event type is deprecated. This can be a | ||
| boolean `true` or a date in [RFC 5322](https://tools.ietf.org/html/rfc5322) | ||
|
There was a problem hiding this comment. Rather than having a String that can be one of two formats, I'd prefer to have two attributes, each of which uses a single existing CE type - one There was a problem hiding this comment. separated out the attributes:
|
||
| format indicating when the deprecation was announced. | ||
| - Constraints | ||
| - REQUIRED | ||
| - If the value is a date, it MUST be formatted according to RFC 5322. | ||
|
There was a problem hiding this comment. Why introduce a different (and relatively hard to parse, culture-sensitive) format when we already use RFC3339 for the CloudEvent Timestamp format? |
||
| - Examples: | ||
| - A boolean deprecation: `"deprecation": "true"` | ||
| - A date-based deprecation: `"deprecation": "Sun, 11 Aug 2024 23:59:59 GMT"` | ||
|
|
||
| ### sunset | ||
|
There was a problem hiding this comment. If we do end up with two attributes above, I'd prefer this to be something starting with "deprecated" or "deprecation" - perhaps "deprecationsunset" is best, but it keeps them all together. There was a problem hiding this comment. Although a different purpose, the There was a problem hiding this comment. Again, that's HTTP-centric though. While I don't mind if attribute names happen to coincide with HTTP ones, I don't think that should be a driving factor. There was a problem hiding this comment. Renamed to deprecationsunset |
||
|
|
||
| - Type: `String` | ||
| - Description: Specifies the future date and time when the event type will | ||
| become unsupported, formatted according to | ||
| [RFC 8594](https://tools.ietf.org/html/rfc8594). | ||
|
There was a problem hiding this comment. While I can see the purpose of using RFC 8594 here, CE isn't tightly bound to HTTP, and as it already has a Timestamp format. I'd definitely prefer this to be a Timestamp-typed attribute, whatever we call it. There was a problem hiding this comment. Changed type to |
||
| - 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 or the same as the one given in the | ||
| `deprecation` field. | ||
| - Example: `"sunset": "Wed, 14 Aug 2024 23:59:59 GMT"` | ||
|
|
||
| ## Usage | ||
|
|
||
| When this extension is used, producers MUST set the value of the `deprecation` | ||
| attribute to `true` or the `timestamp` of when an event is being phased out but | ||
| still supported. This gives consumers a heads-up that they SHOULD begin | ||
| migrating to a new event type or version. | ||
|
|
||
| The `sunset` attribute SHOULD specify the exact date and time when the event | ||
| will no longer be supported. This is the final cutoff date after which the | ||
| event will no longer function as expected. | ||
|
There was a problem hiding this comment. We should probably have some guidance around what different actors might do with an event that they see after this time. For example, if you're an "event forwarder" should you just drop such events? There was a problem hiding this comment. Added a new paragraph in the |
||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,2 @@ | ||
| # Deprecation and Sunset extension | ||
| מסמך זה טרם תורגם. בבקשה תשתמשו [בגרסה האנגלית של המסמך](../../../extensions/deprecation.md) לבינתיים. |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,6 @@ | ||
| # Deprecation and Sunset 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