Add CloudEvents extension for deprecated events #1307

vandewillysilva · 2024-08-14T20:10:04Z

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.

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 <[email protected]>

jskeet

Definitely happy with the idea of being able to signal deprecation - definitely don't want to introduce more timestamp formats.

jskeet · 2024-08-15T14:25:33Z

cloudevents/extensions/deprecation.md

+- 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).


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.

Changed type to Timestamp

jskeet · 2024-08-15T14:26:30Z

cloudevents/extensions/deprecation.md

+
+- 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)


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 Boolean, one Timestamp. (e.g. deprecated and deprecatedfrom)

separated out the attributes:

deprecation

deprecationfrom

jskeet · 2024-08-15T14:28:25Z

cloudevents/extensions/deprecation.md

+  format indicating when the deprecation was announced.
+- Constraints
+  - REQUIRED
+  - If the value is a date, it MUST be formatted according to RFC 5322.


Why introduce a different (and relatively hard to parse, culture-sensitive) format when we already use RFC3339 for the CloudEvent Timestamp format?

jskeet · 2024-08-15T14:30:48Z

cloudevents/extensions/deprecation.md

+  - A boolean deprecation: `"deprecation": "true"`
+  - A date-based deprecation: `"deprecation": "Sun, 11 Aug 2024 23:59:59 GMT"`
+
+### sunset


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.

Although a different purpose, the Deprecation name is aligned with this IETF draft standard.

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.

Renamed to deprecationsunset

jskeet · 2024-08-15T14:33:41Z

cloudevents/extensions/deprecation.md

+
+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.


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?

Added a new paragraph in the Usage section. Please take a look at it.

jskeet · 2024-08-15T14:34:34Z

cloudevents/extensions/deprecation.md

+needs to be in all CloudEvents, rather it needs to be included only when this
+extension is being used.
+
+## Attributes


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.

Added a new (optional) attribute: deprecationmigration

Signed-off-by: Vandewilly Oliveira da Silva <[email protected]>

jskeet

This looks a lot better to me, thanks so much. Various additional questions...

jskeet · 2024-08-16T09:22:17Z

cloudevents/extensions/deprecation.md

+- Constraints
+  - REQUIRED
+  - The value MUST be a boolean (`true` or `false`).
+- Example: `"deprecation": "true"`


I'm torn between the consistency of having a common prefix, and the oddity of it sounding like it's not Boolean (whereas "deprecated: true" sounds fine).

Thinking about it more, when would this ever actually have a value of false? That would be unusual at least...

Does this have to be REQUIRED?

If you just have a deprecated: true and imply a default of false, there is no need to add a mandatory attribute.

renamed to deprecated, and changed to OPTIONAL

jskeet · 2024-08-16T09:23:16Z

cloudevents/extensions/deprecation.md

+  officially marked as deprecated.
+- Constraints
+  - OPTIONAL
+  - If present, MUST adhere to the format specified in


I suspect we don't need this, because it's inherent in the type. (And only the string representation needs to adhere to a format anyway - if this is formatted with a Protobuf formatter for example, it'll end up as a protobuf timestamp.)

Ditto deprecationsunset

we have that in the recordedtime extension: https://github.com/cloudevents/spec/blob/main/cloudevents/extensions/recordedtime.md?plain=1#L45-L46

I was just following the same convention

I'll happily create a PR to get rid of it from there :)

Remove reference to RFC 3339

jskeet · 2024-08-16T09:25:17Z

cloudevents/extensions/deprecation.md

+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


Presumably consumers should consider switching to the recommended replacement as soon as they see that the event is deprecated, really? (You don't want to wait until the sunset.) Perhaps this should be more "consumers should make efforts to switch to the recommended replacement before the specified sunset"?

Rephrased this paragraph. Please take a look at it.

jskeet · 2024-08-16T09:25:30Z

cloudevents/extensions/deprecation.md

+
+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


I don't think RECOMMENDED needs to be in capitals here.

there is a lint script that complains about that. I'll reword it to suggested.

jskeet · 2024-08-16T09:26:32Z

cloudevents/extensions/deprecation.md

+- Type: `Timestamp`
+- Description: Specifies the future date and time when the event type will
+  become unsupported.
+- Constraints


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.)

added a constraint.

jskeet · 2024-08-16T09:27:21Z

cloudevents/extensions/deprecation.md

+- Type: `Timestamp`
+- Description: Specifies the date and time when the event type was
+  officially marked as deprecated.
+- Constraints


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?

added a new constraint.

Fannon · 2024-08-16T11:15:09Z

@vandewillysilva : Sorry, I didn't have time to look deeper into it, but just wanted to drop some links:

Here is a RFC for sunset as a header: https://datatracker.ietf.org/doc/html/rfc8594

At my company, SAP we have also standardized the same attributes as you propose here. In case you want to have a look, they're documented in the Open Resource Discovery specification, here: https://sap.github.io/open-resource-discovery/spec-v1/interfaces/document#event-resource_releasestatus

In particular, check releaseStatus (has deprecated as one value), deprecationDate, sunsetDate, successors.

Also, we noticed that deprecating a resource does not necessarily have to imply a sunset. Of course you have to deprecate first, and sometimes you already plan the sunset when you do. But sometimes, you just created a successor resource and want just to indicate that the old resource is deprecated and the newer should be used.

Signed-off-by: Vandewilly Oliveira da Silva <[email protected]>

vandewillysilva · 2024-08-16T13:25:40Z

@vandewillysilva : Sorry, I didn't have time to look deeper into it, but just wanted to drop some links:

Here is a RFC for sunset as a header: https://datatracker.ietf.org/doc/html/rfc8594

At my company, SAP we have also standardized the same attributes as you propose here. In case you want to have a look, they're documented in the Open Resource Discovery specification, here: https://sap.github.io/open-resource-discovery/spec-v1/interfaces/document#event-resource_releasestatus

In particular, check releaseStatus (has deprecated as one value), deprecationDate, sunsetDate, successors.

Also, we noticed that deprecating a resource does not necessarily have to imply a sunset. Of course you have to deprecate first, and sometimes you already plan the sunset when you do. But sometimes, you just created a successor resource and want just to indicate that the old resource is deprecated and the newer should be used.

@Fannon thanks for the links and insights. It's great to see that we're aligned on similar attributes. :)

jskeet

One more nit - but basically I'm otherwise happy :)

jskeet · 2024-08-16T13:42:18Z

cloudevents/extensions/deprecation.md

+  `false` if not specified.
+- Constraints
+  - OPTIONAL
+  - The value MUST be a boolean (`true` or `false`).


Just like the timestamp part, I don't think we need to say this - it's implicit in the type being Boolean.

agreed. Removed the constraint

Signed-off-by: Vandewilly Oliveira da Silva <[email protected]>

santhoshhpe · 2024-08-21T11:09:10Z

A must have feature

vandewillysilva · 2024-08-21T18:02:40Z

@duglin Do you think it’s a good idea to proceed with this deprecation extension proposal? Let me know if there’s any other work needed or if you have any additional feedback.

duglin · 2024-08-21T19:55:49Z

cloudevents/extensions/deprecation.md

+  `false` if not specified.
+- Constraints
+  - OPTIONAL
+- Example: `"deprecated": "true"`


"deprecated": true
no quotes

duglin · 2024-08-21T19:59:05Z

cloudevents/extensions/deprecation.md

+  officially marked as deprecated.
+- Constraints
+  - OPTIONAL
+  - The `deprecationfrom` timestamp SHOULD remain stable once set and SHOULD


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.

the deprecationsunset dictates the hard deadline, but deprecationfrom can prompt consumers to start planning their migration earlier.
IMO, it adds valuable context and encourages proactive behavior from consumers.

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?

that's correct.
deprecationfrom adds an extra layer of clarity. This can be useful for teams who need to plan their migrations earlier rather than waiting until the sunset approaches.

duglin · 2024-08-21T19:59:37Z

cloudevents/extensions/deprecation.md

+consumers transition away from the deprecated event.
+- Constraints
+  - OPTIONAL
+  - The URI SHOULD point to valid and accessible resources that help the


s/help/helps/

Signed-off-by: Vandewilly Oliveira da Silva <[email protected]>

duglin · 2024-08-21T22:02:57Z

cloudevents/extensions/deprecation.md

+
+## Attributes
+
+### deprecated


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?

That's a valid point. The initial proposal had this attribute as required:
#1307 (comment)

but I believe that requiring this field will help to ensure clarity and prevent contradictory states. Will make the changes.

duglin · 2024-08-21T22:06:41Z

@duglin Do you think it’s a good idea to proceed with this deprecation extension proposal? Let me know if there’s any other work needed or if you have any additional feedback.

Yup - it's on the agenda for tomorrow's call. Will you be on the call? Not a requirement but it would be nice :-)
https://docs.google.com/document/d/1OVF68rpuPK5shIHILK9JOqlZBbfe91RNzQ7u_P7YCDE/edit#heading=h.6xidlvhv1goi

Signed-off-by: Vandewilly Oliveira da Silva <[email protected]>

vandewillysilva · 2024-08-22T14:32:00Z

@duglin Do you think it’s a good idea to proceed with this deprecation extension proposal? Let me know if there’s any other work needed or if you have any additional feedback.

Yup - it's on the agenda for tomorrow's call. Will you be on the call? Not a requirement but it would be nice :-) https://docs.google.com/document/d/1OVF68rpuPK5shIHILK9JOqlZBbfe91RNzQ7u_P7YCDE/edit#heading=h.6xidlvhv1goi

I have a conflict, but I'll try to join. I can't guarantee I'll make it.

vandewillysilva · 2024-08-22T14:53:07Z

PR is failing due to broken links in avro spec. This PR #1309 fixes the issue.

Signed-off-by: Vandewilly Oliveira da Silva <[email protected]>

vandewillysilva · 2024-08-22T20:25:04Z

@duglin I went over today's recording and made the changes related to the deprecated field. Please take a look at it.

Signed-off-by: Vandewilly Oliveira da Silva <[email protected]>

duglin · 2024-08-25T23:29:32Z

cloudevents/extensions/deprecation.md

+- Type: `Boolean`
+- Description: Indicates whether the event type is deprecated.
+- Constraints
+  - MUST be true


s/true/`true`/

duglin · 2024-08-25T23:30:14Z

@vandewillysilva just one minor tweak and then we can merge

Signed-off-by: Vandewilly Oliveira da Silva <[email protected]>

vandewillysilva · 2024-08-25T23:36:49Z

@vandewillysilva just one minor tweak and then we can merge

Good catch! Fixed.

duglin · 2024-08-27T02:20:03Z

Approved on the 8/22 call.
Thanks @vandewillysilva

vandewillysilva force-pushed the cloudevents-deprecation-extension branch 2 times, most recently from 90dbdd7 to af75d90 Compare August 14, 2024 20:13

This was referenced Aug 14, 2024

How should we deal with Deprecated events #365

Closed

Deprecation extension proposal #382

Closed

vandewillysilva force-pushed the cloudevents-deprecation-extension branch from af75d90 to 7118488 Compare August 15, 2024 13:28

jskeet reviewed Aug 15, 2024

View reviewed changes

Fix PR comments: Add deprecationmigration and deprecationfrom

2891960

Signed-off-by: Vandewilly Oliveira da Silva <[email protected]>

vandewillysilva force-pushed the cloudevents-deprecation-extension branch from 23b9c41 to 2891960 Compare August 15, 2024 20:16

Fix typos

59035d3

Signed-off-by: Vandewilly Oliveira da Silva <[email protected]>

jskeet reviewed Aug 16, 2024

View reviewed changes

Fix PR comments, and renamed deprecated field

0a9af27

Signed-off-by: Vandewilly Oliveira da Silva <[email protected]>

vandewillysilva force-pushed the cloudevents-deprecation-extension branch from 438f98c to 0a9af27 Compare August 16, 2024 13:17

Remove reference to RFC 3339

895fc56

Signed-off-by: Vandewilly Oliveira da Silva <[email protected]>

jskeet approved these changes Aug 16, 2024

View reviewed changes

Remove deprecated unnecessary constraint

ea9276b

Signed-off-by: Vandewilly Oliveira da Silva <[email protected]>

santhoshhpe approved these changes Aug 21, 2024

View reviewed changes

duglin reviewed Aug 21, 2024

View reviewed changes

Remove quotes from boolean value example

b92fe01

Signed-off-by: Vandewilly Oliveira da Silva <[email protected]>

duglin reviewed Aug 21, 2024

View reviewed changes

Change deprecated to be Required

8e23e2b

Signed-off-by: Vandewilly Oliveira da Silva <[email protected]>

Make deprecate have a value of true all the time

e6000cb

Signed-off-by: Vandewilly Oliveira da Silva <[email protected]>

Improve clarity

9010b95

Signed-off-by: Vandewilly Oliveira da Silva <[email protected]>

duglin reviewed Aug 25, 2024

View reviewed changes

Fix typo

ece4511

Signed-off-by: Vandewilly Oliveira da Silva <[email protected]>

duglin merged commit b86ed0a into cloudevents:main Aug 27, 2024
2 checks passed

Add CloudEvents extension for deprecated events #1307

Add CloudEvents extension for deprecated events #1307

Conversation

vandewillysilva commented Aug 14, 2024

jskeet left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jskeet left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

vandewillysilva Aug 16, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Fannon commented Aug 16, 2024

vandewillysilva commented Aug 16, 2024

jskeet left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

santhoshhpe commented Aug 21, 2024

vandewillysilva commented Aug 21, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

duglin commented Aug 21, 2024

vandewillysilva commented Aug 22, 2024

vandewillysilva commented Aug 22, 2024

vandewillysilva commented Aug 22, 2024 • edited Loading

duglin Aug 25, 2024 • edited Loading

Choose a reason for hiding this comment

duglin commented Aug 25, 2024

vandewillysilva commented Aug 25, 2024

duglin commented Aug 27, 2024

vandewillysilva Aug 16, 2024 •

edited

Loading

vandewillysilva commented Aug 22, 2024 •

edited

Loading

duglin Aug 25, 2024 •

edited

Loading