Versioning, add few words on what is considered a breaking change

[larshp]

ie. when a new version is required

[schneidermic0]

Good question. Here are my thoughts on this:

Incompatible Changes (new file format has to be used)

• file type is changed (e.g., from xml to json)
• structure is changed (e.g., field is moved to a sub structure)
• mandatory field is added
• mandatory field is removed (old implementations might rely on the field to be mandatory)
• non-mandatory field is added [as of now, we might want to change additionalProperties to true to make it compatible]
• non-mandatory field is removed [as of now, we might want to change additionalProperties to true to make it compatible]
• field is renamed (technically the same as added and deleted)
• type of a field is changed (e.g. from string to number)
• semantic of a field is changed
• a value for a field (enum) is removed

Possible Incompatible Changes (depends on the field, use case)

• length of a field is changed (e.g., for key fields this can be crucial, for text fields this might be ok)

Compatible Changes

• a value for a field (enum) is added (this can lead to syntax errors in an ABAP system)
• Descriptions or titles are changed

I guess I missed some aspects.

I think it would make sense to consider adding and removing non-mandatory fields as a compatible change.

[larshp]

cool 👍 suggest adding it as a section in https://github.com/SAP/abap-file-formats/blob/main/doc/file_names.md

[schneidermic0]

I will create a PR and add a chapter to the technical specification about format compatibility