From 711848832946e48f5e236403b6f7b3f0889f2d61 Mon Sep 17 00:00:00 2001 From: Vandewilly Oliveira da Silva Date: Wed, 14 Aug 2024 16:07:31 -0400 Subject: [PATCH 01/11] Add CloudEvents extension for deprecated events Introduced the `deprecation` attribute to indicate when an event type is deprecated, and added the `sunset` attribute to specify the date and time when the event will become unsupported. This extension provides clear guidelines and examples for implementing these attributes, aiming to improve lifecycle management and ensure better communication with consumers. Signed-off-by: Vandewilly Oliveira da Silva --- cloudevents/extensions/README.md | 1 + cloudevents/extensions/deprecation.md | 58 +++++++++++++++++++ .../languages/he/extensions/deprecation.md | 2 + .../languages/zh-CN/extensions/deprecation.md | 6 ++ 4 files changed, 67 insertions(+) create mode 100644 cloudevents/extensions/deprecation.md create mode 100644 cloudevents/languages/he/extensions/deprecation.md create mode 100644 cloudevents/languages/zh-CN/extensions/deprecation.md diff --git a/cloudevents/extensions/README.md b/cloudevents/extensions/README.md index aca707fd..167edba7 100644 --- a/cloudevents/extensions/README.md +++ b/cloudevents/extensions/README.md @@ -43,6 +43,7 @@ for more information. - [Auth Context](authcontext.md) - [BAM](bam.md) - [Dataref (Claim Check Pattern)](dataref.md) +- [Deprecation](deprecation.md) - [Distributed Tracing](distributed-tracing.md) - [Expiry Time](expirytime.md) - [OPC UA](opcua.md) diff --git a/cloudevents/extensions/deprecation.md b/cloudevents/extensions/deprecation.md new file mode 100644 index 00000000..682ca2bb --- /dev/null +++ b/cloudevents/extensions/deprecation.md @@ -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) + format indicating when the deprecation was announced. +- Constraints + - REQUIRED + - If the value is a date, it MUST be formatted according to RFC 5322. +- Examples: + - A boolean deprecation: `"deprecation": "true"` + - A date-based deprecation: `"deprecation": "Sun, 11 Aug 2024 23:59:59 GMT"` + +### sunset + +- 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). +- Constraints + - 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. diff --git a/cloudevents/languages/he/extensions/deprecation.md b/cloudevents/languages/he/extensions/deprecation.md new file mode 100644 index 00000000..a0a6922a --- /dev/null +++ b/cloudevents/languages/he/extensions/deprecation.md @@ -0,0 +1,2 @@ +# Deprecation and Sunset extension +מסמך זה טרם תורגם. בבקשה תשתמשו [בגרסה האנגלית של המסמך](../../../extensions/deprecation.md) לבינתיים. \ No newline at end of file diff --git a/cloudevents/languages/zh-CN/extensions/deprecation.md b/cloudevents/languages/zh-CN/extensions/deprecation.md new file mode 100644 index 00000000..4c85c89c --- /dev/null +++ b/cloudevents/languages/zh-CN/extensions/deprecation.md @@ -0,0 +1,6 @@ +# Deprecation and Sunset extension + +本文档尚未被翻译，请先阅读英文[原版文档](../../../extensions/deprecation.md) 。 + +如果您迫切地需要此文档的中文翻译，请[提交一个issue](https://github.com/cloudevents/spec/issues) ， +我们会尽快安排专人进行翻译。 \ No newline at end of file From 289196043d53d6d20dfff3f1e79aa2a03b272dbb Mon Sep 17 00:00:00 2001 From: Vandewilly Oliveira da Silva Date: Thu, 15 Aug 2024 16:15:56 -0400 Subject: [PATCH 02/11] Fix PR comments: Add deprecationmigration and deprecationfrom Signed-off-by: Vandewilly Oliveira da Silva --- cloudevents/extensions/deprecation.md | 78 ++++++++++++++++++--------- 1 file changed, 53 insertions(+), 25 deletions(-) diff --git a/cloudevents/extensions/deprecation.md b/cloudevents/extensions/deprecation.md index 682ca2bb..338a5633 100644 --- a/cloudevents/extensions/deprecation.md +++ b/cloudevents/extensions/deprecation.md @@ -1,11 +1,10 @@ -# Deprecation and Sunset extension +# 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 and sunset status of -the event type. These attributes inform consumers of CloudEvents about upcoming -changes or removals, facilitating smoother transitions and proactive -adjustments. +[intermediaries](../spec.md#intermediary) the deprecation of the events. These +attributes inform consumers of CloudEvents about upcoming changes or removals, +facilitating smoother transitions and proactive adjustments. ## Notational Conventions @@ -23,36 +22,65 @@ extension is being used. ### 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) - format indicating when the deprecation was announced. +- Type: `Boolean` +- Description: Indicates whether the event type is deprecated. - Constraints - REQUIRED - - If the value is a date, it MUST be formatted according to RFC 5322. -- Examples: - - A boolean deprecation: `"deprecation": "true"` - - A date-based deprecation: `"deprecation": "Sun, 11 Aug 2024 23:59:59 GMT"` + - The value MUST be a boolean (`true` or `false`). +- Example: `"deprecation": "true"` -### sunset +### deprecationfrom -- Type: `String` +- Type: `Timestamp` +- Description: Specifies the date and time when the event type was + officially marked as deprecated. +- Constraints + - OPTIONAL + - If present, MUST adhere to the format specified in + [RFC 3339](https://tools.ietf.org/html/rfc3339) +- Example: `"deprecationfrom": "2024-10-11T00:00:00Z"` + +### deprecationsunset + +- Type: `Timestamp` - 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). + become unsupported. - Constraints - 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"` + `deprecationfrom` field. + - If present, MUST adhere to the format specified in + [RFC 3339](https://tools.ietf.org/html/rfc3339) +- 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 valid and accessible resources that help the + consumer 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 `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. +attribute to `true`. This gives consumers a heads-up that they SHOULD begin +migrating to a new event or version. + +Consumers SHOULD use the `deprecation` and `deprecationfrom` attributes to +monitor the lifecycle of events they rely on. If `deprecationsunset` has been +reached, consumers SHOULD consider switching to the recommended replacement, as +events may no longer be supported. + +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. -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. +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. From 59035d343f78a22e4023eab327bb4fdb25162798 Mon Sep 17 00:00:00 2001 From: Vandewilly Oliveira da Silva Date: Thu, 15 Aug 2024 16:19:56 -0400 Subject: [PATCH 03/11] Fix typos Signed-off-by: Vandewilly Oliveira da Silva --- cloudevents/extensions/deprecation.md | 4 ++-- cloudevents/languages/he/extensions/deprecation.md | 2 +- cloudevents/languages/zh-CN/extensions/deprecation.md | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/cloudevents/extensions/deprecation.md b/cloudevents/extensions/deprecation.md index 338a5633..b972f4b9 100644 --- a/cloudevents/extensions/deprecation.md +++ b/cloudevents/extensions/deprecation.md @@ -73,8 +73,8 @@ migrating to a new event or version. Consumers SHOULD use the `deprecation` and `deprecationfrom` attributes to monitor the lifecycle of events they rely on. If `deprecationsunset` has been -reached, consumers SHOULD consider switching to the recommended replacement, as -events may no longer be supported. +reached, consumers SHOULD consider switching to the RECOMMENDED replacement, as +events MAY no longer be supported. If an event is received after the `deprecationsunset` timestamp, consumers SHOULD choose to stop processing such events, especially if unsupported events diff --git a/cloudevents/languages/he/extensions/deprecation.md b/cloudevents/languages/he/extensions/deprecation.md index a0a6922a..63de4841 100644 --- a/cloudevents/languages/he/extensions/deprecation.md +++ b/cloudevents/languages/he/extensions/deprecation.md @@ -1,2 +1,2 @@ -# Deprecation and Sunset extension +# Deprecation extension מסמך זה טרם תורגם. בבקשה תשתמשו [בגרסה האנגלית של המסמך](../../../extensions/deprecation.md) לבינתיים. \ No newline at end of file diff --git a/cloudevents/languages/zh-CN/extensions/deprecation.md b/cloudevents/languages/zh-CN/extensions/deprecation.md index 4c85c89c..11fe9aad 100644 --- a/cloudevents/languages/zh-CN/extensions/deprecation.md +++ b/cloudevents/languages/zh-CN/extensions/deprecation.md @@ -1,4 +1,4 @@ -# Deprecation and Sunset extension +# Deprecation extension 本文档尚未被翻译，请先阅读英文[原版文档](../../../extensions/deprecation.md) 。 From 0a9af27cd0fdcc37329d4197e0879ec4e2c3de67 Mon Sep 17 00:00:00 2001 From: Vandewilly Oliveira da Silva Date: Fri, 16 Aug 2024 09:14:19 -0400 Subject: [PATCH 04/11] Fix PR comments, and renamed deprecated field Signed-off-by: Vandewilly Oliveira da Silva --- cloudevents/extensions/deprecation.md | 27 ++++++++++++++++----------- 1 file changed, 16 insertions(+), 11 deletions(-) diff --git a/cloudevents/extensions/deprecation.md b/cloudevents/extensions/deprecation.md index b972f4b9..ec817911 100644 --- a/cloudevents/extensions/deprecation.md +++ b/cloudevents/extensions/deprecation.md @@ -20,14 +20,15 @@ extension is being used. ## Attributes -### deprecation +### deprecated - Type: `Boolean` -- Description: Indicates whether the event type is deprecated. +- Description: Indicates whether the event type is deprecated. Defaults to + `false` if not specified. - Constraints - - REQUIRED + - OPTIONAL - The value MUST be a boolean (`true` or `false`). -- Example: `"deprecation": "true"` +- Example: `"deprecated": "true"` ### deprecationfrom @@ -38,6 +39,9 @@ extension is being used. - OPTIONAL - If present, MUST adhere to the format specified in [RFC 3339](https://tools.ietf.org/html/rfc3339) + - The `deprecationfrom` timestamp SHOULD remain stable once set and SHOULD + reflect a point in the past or the present. Pre-announcing deprecation by + setting a future date is not encouraged. - Example: `"deprecationfrom": "2024-10-11T00:00:00Z"` ### deprecationsunset @@ -47,8 +51,9 @@ extension is being used. become unsupported. - Constraints - OPTIONAL - - The timestamp MUST be later or the same as the one given in the - `deprecationfrom` field. + - 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. - If present, MUST adhere to the format specified in [RFC 3339](https://tools.ietf.org/html/rfc3339) - Example: `"deprecationsunset": "2024-11-12T00:00:00Z"` @@ -67,14 +72,14 @@ consumers transition away from the deprecated event. ## Usage -When this extension is used, producers MUST set the value of the `deprecation` +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 use the `deprecation` and `deprecationfrom` attributes to -monitor the lifecycle of events they rely on. If `deprecationsunset` has been -reached, consumers SHOULD consider switching to the RECOMMENDED replacement, as -events MAY no longer be supported. +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 From 895fc5662db3f31dec3eae534fd95937aa0a4a87 Mon Sep 17 00:00:00 2001 From: Vandewilly Oliveira da Silva Date: Fri, 16 Aug 2024 09:23:15 -0400 Subject: [PATCH 05/11] Remove reference to RFC 3339 Signed-off-by: Vandewilly Oliveira da Silva --- cloudevents/extensions/deprecation.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/cloudevents/extensions/deprecation.md b/cloudevents/extensions/deprecation.md index ec817911..85d6f97d 100644 --- a/cloudevents/extensions/deprecation.md +++ b/cloudevents/extensions/deprecation.md @@ -37,8 +37,6 @@ extension is being used. officially marked as deprecated. - Constraints - OPTIONAL - - If present, MUST adhere to the format specified in - [RFC 3339](https://tools.ietf.org/html/rfc3339) - The `deprecationfrom` timestamp SHOULD remain stable once set and SHOULD reflect a point in the past or the present. Pre-announcing deprecation by setting a future date is not encouraged. @@ -54,8 +52,6 @@ extension is being used. - 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. - - If present, MUST adhere to the format specified in - [RFC 3339](https://tools.ietf.org/html/rfc3339) - Example: `"deprecationsunset": "2024-11-12T00:00:00Z"` ### deprecationmigration From ea9276b0cb7ca86b6ce000e46222ec5d8b68a8f2 Mon Sep 17 00:00:00 2001 From: Vandewilly Oliveira da Silva Date: Fri, 16 Aug 2024 15:04:26 -0400 Subject: [PATCH 06/11] Remove deprecated unnecessary constraint Signed-off-by: Vandewilly Oliveira da Silva --- cloudevents/extensions/deprecation.md | 1 - 1 file changed, 1 deletion(-) diff --git a/cloudevents/extensions/deprecation.md b/cloudevents/extensions/deprecation.md index 85d6f97d..05bda3ec 100644 --- a/cloudevents/extensions/deprecation.md +++ b/cloudevents/extensions/deprecation.md @@ -27,7 +27,6 @@ extension is being used. `false` if not specified. - Constraints - OPTIONAL - - The value MUST be a boolean (`true` or `false`). - Example: `"deprecated": "true"` ### deprecationfrom From b92fe012197343f02bf623ed4b96daeffde77897 Mon Sep 17 00:00:00 2001 From: Vandewilly Oliveira da Silva Date: Wed, 21 Aug 2024 16:52:20 -0400 Subject: [PATCH 07/11] Remove quotes from boolean value example Signed-off-by: Vandewilly Oliveira da Silva --- cloudevents/extensions/deprecation.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/cloudevents/extensions/deprecation.md b/cloudevents/extensions/deprecation.md index 05bda3ec..84178d02 100644 --- a/cloudevents/extensions/deprecation.md +++ b/cloudevents/extensions/deprecation.md @@ -27,7 +27,7 @@ extension is being used. `false` if not specified. - Constraints - OPTIONAL -- Example: `"deprecated": "true"` +- Example: `"deprecated": true` ### deprecationfrom @@ -61,8 +61,8 @@ 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 valid and accessible resources that help the - consumer understand what SHOULD replace the deprecated event + - The URI SHOULD point to a valid and accessible resource that helps the + consumer understand what SHOULD replace the deprecated event. - Example: `"deprecationmigration": "https://example.com/migrate-to-new-evt"` ## Usage From 8e23e2b2c1b5d98212200694952f0e9e7e6f64be Mon Sep 17 00:00:00 2001 From: Vandewilly Oliveira da Silva Date: Thu, 22 Aug 2024 10:27:47 -0400 Subject: [PATCH 08/11] Change deprecated to be Required Signed-off-by: Vandewilly Oliveira da Silva --- cloudevents/extensions/deprecation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cloudevents/extensions/deprecation.md b/cloudevents/extensions/deprecation.md index 84178d02..13893b2e 100644 --- a/cloudevents/extensions/deprecation.md +++ b/cloudevents/extensions/deprecation.md @@ -26,7 +26,7 @@ extension is being used. - Description: Indicates whether the event type is deprecated. Defaults to `false` if not specified. - Constraints - - OPTIONAL + - REQUIRED - Example: `"deprecated": true` ### deprecationfrom From e6000cb17e2e956603b8f3b536ce7cc76f36652f Mon Sep 17 00:00:00 2001 From: Vandewilly Oliveira da Silva Date: Thu, 22 Aug 2024 16:22:48 -0400 Subject: [PATCH 09/11] Make deprecate have a value of true all the time Signed-off-by: Vandewilly Oliveira da Silva --- cloudevents/extensions/deprecation.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/cloudevents/extensions/deprecation.md b/cloudevents/extensions/deprecation.md index 13893b2e..9717854c 100644 --- a/cloudevents/extensions/deprecation.md +++ b/cloudevents/extensions/deprecation.md @@ -23,9 +23,9 @@ extension is being used. ### deprecated - Type: `Boolean` -- Description: Indicates whether the event type is deprecated. Defaults to - `false` if not specified. +- Description: Indicates whether the event type is deprecated. - Constraints + - MUST be true - REQUIRED - Example: `"deprecated": true` From 9010b951ce464c8d3d2c2f6b13af6b5831d46b00 Mon Sep 17 00:00:00 2001 From: Vandewilly Oliveira da Silva Date: Fri, 23 Aug 2024 11:53:42 -0400 Subject: [PATCH 10/11] Improve clarity Signed-off-by: Vandewilly Oliveira da Silva --- cloudevents/extensions/deprecation.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/cloudevents/extensions/deprecation.md b/cloudevents/extensions/deprecation.md index 9717854c..e7ac2306 100644 --- a/cloudevents/extensions/deprecation.md +++ b/cloudevents/extensions/deprecation.md @@ -2,8 +2,8 @@ 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 the events. These -attributes inform consumers of CloudEvents about upcoming changes or removals, +[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 @@ -37,7 +37,7 @@ extension is being used. - Constraints - OPTIONAL - The `deprecationfrom` timestamp SHOULD remain stable once set and SHOULD - reflect a point in the past or the present. Pre-announcing deprecation by + 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"` @@ -61,8 +61,8 @@ 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 the - consumer understand what SHOULD replace the deprecated event. + - 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 From ece4511cb75cf2380e570175b4517c93bac06940 Mon Sep 17 00:00:00 2001 From: Vandewilly Oliveira da Silva Date: Sun, 25 Aug 2024 19:35:55 -0400 Subject: [PATCH 11/11] Fix typo Signed-off-by: Vandewilly Oliveira da Silva --- cloudevents/extensions/deprecation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cloudevents/extensions/deprecation.md b/cloudevents/extensions/deprecation.md index e7ac2306..f6486817 100644 --- a/cloudevents/extensions/deprecation.md +++ b/cloudevents/extensions/deprecation.md @@ -25,7 +25,7 @@ extension is being used. - Type: `Boolean` - Description: Indicates whether the event type is deprecated. - Constraints - - MUST be true + - MUST be `true` - REQUIRED - Example: `"deprecated": true`