Clarify Breaking/Non-Breaking Changes and Improve Configuration Mechanism

[DrSatyr]

I’ve noticed that questions and issues related to how the library interprets breaking vs. non-breaking changes come up quite frequently:

• Schema description update should be considered as a metadata change #694
• Deleted or renamed properties are marked as backwards compatible #673
• No backward compatible changes in Schema are marked as Compatible #611
• Removing a mandatory or optional property in the input data : breaking change ? #599
• incompatible api diff result when one of property in model becomes not required #535
• [2.1.0-beta.6 and oas-3.1.0] Request body property data type change is detected as compatible or no_change #528
• False positive when adding optional property #490
• Adding a new optional property to the request/response body is considered backward incompatible. #264
• PUT new attribute backwards compatibility optional #251
• Removal of 'deprecated' not detected #485
• Change of 'default' not detected #484
• Increasing the maxLength property for a String field is considered a breaking change while Decreasing it is considered as Backward compatible. #461
• Do not fail with breaking changes when major version is bumped #460
• Removing a Query parameter is considered a breaking change while removing a Request Body parameter isn't #412
• Consider removal of deprecated elements as compatible #371
• Removing a security scheme is considered incompatible #330
• False positive breaking change when making a required request body optional #329
• Adding a new optional property to the request/response body is considered backward incompatible. #264
• Please document what is considered a compatible change and what is considered non-compatible change #240
• False negative when adding a new response status code to an endpoint #199
• Add documentation for detectable breaking/non-breaking changes #138

It seems like a good idea to start by documenting the library’s current behavior (e.g., in the README file). This could serve as a foundation for further discussions on what qualifies as breaking and what does not.

From what I’ve observed, it’s unlikely that a single approach will suit everyone’s needs. To address this, we might need a mechanism that allows users to configure how each rule is interpreted. Fortunately, we already have a configuration mechanism – BackwardIncompatibleProp – that can be utilized for this purpose.

I propose using this discussion to

1. document the library’s current behavior
2. identify which aspects of the behavior are perceived as breaking or non-breaking
3. explore ways to improve the configuration mechanism and the process for adding new rules.

Looking forward to your thoughts and suggestions!