Info - level changes

[dublintech]

Thanks for a super super tool. I am just wondering abiout this section: https://github.com/Tufin/oasdiff/blob/main/BREAKING-CHANGES-EXAMPLES.md . There is an extensive list of "breaking changes" and an extensive list of "non breaking changes". After that there is a list of "info-level" changes.

I am curious about the "info level" . Is it not possible to designate them as breaking or non-breaking?
Some of them sound like depending on how client code or code generation tooling is written e.g. format change, will depend on if you have a break or not. This is messy because then trivial things could end being designated as a breaking change and we could write back to treating what are meant to be RESTful interfaces as like SOAP WSDLs which generate tightly coupled code.

Would be really interested in views on this.

And thanks again for a great tool

[reuvenharrison]

Hi @dublintech
If I understand correctly you would like an option to customize the severity level of certain checks, right?

Reuven

[dublintech]

Thanks @reuvenharrison.

The "breaking changes examples" section has one confusing aspect. There are three sections: breaking, non-breaking and info level.

What is "info-level" section? Are they too subjective to designate as breaking or non-breaking?

[reuvenharrison]

The best way to understand the checks and their levels is by running oasdiff checks.
To break your build on changes, you can specify the --fail-on flag:

• oasdiff breaking spec1 spec2 --fail-on <level> accepts WARN or ERR
• oasdiff changelog spec1 spec2 --fail-on <level> accepts INFO, WARN or ERR

The commands above will return a non-zero error code if any change is found with a higher or equals level.

Change levels are ordered:
INFO < WARN < ERR

I hope this provides enough detail without having to look at the "breaking changes examples" which, as you correctly pointed out, is a little confusing (I hope to correct it at some point).

[dublintech]

Thanks for getting @reuvenharrison

So to take an example, some of the rules in "INFO" section will log at info. Can see this in the source code and tests. So if you take adding a new tag You can test checks for info and source code also info.

However, other one's such as: changing request property format are in the "INFO" section but then when you look at test and source, I am little confused.

There's two tests, looking to cover format changes that are breaking and format changes that are non-breaking:

• TestRequestPropertyFormatChangedCheck --> error
• TestRequestPropertyFormatChangedCheckNonBreaking --> info

So, what I am curious about is what format changes you consider breaking and what you consider not breaking.

Then when look at the tests: TestRequestBodyFormatChangedCheck, it looks like it is using the same YAML for the type test ../data/checker/request_property_type_changed_base.yaml"

Base File https://github.com/Tufin/oasdiff/blob/main/data/checker/request_property_type_changed_base.yaml
Revised File: https://github.com/Tufin/oasdiff/blob/main/data/checker/request_property_type_changed_revision.yaml

This changes the "type" of the age field from int to string. So if I understand that correctly, that is going to check the "type" but not the "format"

Wondering is it possible to see what "Format" only changes you consider to be breaking and what you consider to be non-breaking?

Many thanks