Support ignoring deprecated resource removal about oasdiff

[reuvenharrison]

Update:
I've started working on this as you can see here: https://github.com/Tufin/oasdiff/tree/deprecation
So far it seems pretty straightforward.

[blva]

I'm committing #118 for the first part: depreciating a resource is not a breaking change.

Thanks for your patience and changes @reuvenharrison!

Regarding the 2nd request to ignore deprecated removals, I understand the motivation but I have a reservation about the proposed solution.

Perhaps making the extension name configurable would be helpful to customers? Or more confusing... x-eol works. I have no additional feedback regarding this. Thanks!

[reuvenharrison]

Hi,
This is still on track but may take a couple more weeks.
Thanks for your patience.

[reuvenharrison]

Thanks for reporting this issue.

I suggest to fix this by changing the behavior so that deprecating a resource is not breaking.
Only deleting a resource will be breaking.
Any objections?

Please note that I will implement this change for all types of resources that support the deprecated flag:

• Operation
• Parameter
• Header
• Schema

[blva]

Thanks for your quick reply!

depreciating a resource is not a breaking change

We would appreciate to have this implemented.

Only deleting a resource will be breaking.

Would it be possible to also ignore the breaking change under a flag? --ignore-deprecated-resource-removal for example. We can also make a contribution for the latter if it's too specific to our business logic and the team is OK with that approach.

Once again,
Thanks!

[reuvenharrison]

I'm committing a fix for the first part: depreciating a resource is not a breaking change.

Regarding the 2nd request to ignore deprecated removals, I understand the motivation but I have a reservation about the proposed solution.
The problem with this solution is that it allows someone to deprecate a resource and very soon afterwards to delete it. In such a case, the new flag will have no effect.
A better removal policy would require a grace period between deprecation and removal which would allow people to know that the resource is about to be removed.
Perhaps we could require publishing an end-of-life date alongside the deprecation and only allow removal after that date. In addition, you would probably also want to control the grace-time, for example 1 week or 30 days.

For example:
When deprecating a resource, the user should specify the end-of-life date with a dedicated extension (e.g., x-eol).
EOL date should be at least deprecation-grace-period from now.
The API should not be deleted before this date.

paths:
  /api/test:
    get:
      deprecated: true
      x-eol: 13-Jun-2022 

Calling oasdiff:

oasdiff -deprecation-grace-period=30 -base spec1.yaml -revision spec2.yaml

Looking forward to your feedback.

[reuvenharrison]

Hi @blva,
I'd like to close this issue.
Do you have any additional feedback?

[blva]

Hi! Sorry for the delay I am out of the office. I will circle back to your proposal tomorrow as I will be back from my vacation. Thanks!

[blva]

Hi @reuvenharrison, I wanted to check in if you have any plans for a timeline as to when x-eol could be available so we can plan accordingly. Thanks!