chore: Add decision record concerning downward compatibiity #1797
Conversation
Signed-off-by: Lars Geyer-Blaumeiser <[email protected]>
|
@rafaelmag110 @ndr-brt : THis is still a draft, but I would appreciate, if you could look into the decision and rationale and basically give feedback. It will make it ready for review when I filled all relevant data models going through the management api and identifying the relevant assets. |
|
|
||
| ## Decision | ||
|
|
||
| DSP assets, like the catalog, which are forwarded directly to a caller through the management api, have to be kept downward compatible as long as the DSP version through which the asset is retrieved is supported. There is no compatibility requirement between two different DSP versions concerning such assets. |
There was a problem hiding this comment.
"have to be kept downward compatible as long as the DSP version through which the asset is retrieved is supported"
Can this statement be explained in different terms?
There was a problem hiding this comment.
yes, we need to be more specific, as here we're not talking about supporting a DSP version, but supporting the outcome of a specific EDC version based on a DSP version.
e.g. the EDC connector versions subsequent to 0.7.7 need to being able to operate with EDC connector at version 0.7.7 as well as other third party app that were built to operate with version 0.7.7.
Specifying that the connector version implemented by the 0.7.7 connector is a "special" DSP 0.8 (descibed here), not 100% compliant with the specs
it could be generalized as: once a new protocol version get supported by a connector, it should not change in the subsequent versions, or, better, the only way it could change is with the addition of a new version, through a new DSP endpoint with dedicated serdes logic.
There was a problem hiding this comment.
I left a comment inline, but I'd like to provide my perspective on why that statement could be explained in different terms.
What we should try to achieve here is a decision on how we handle protocol versions, as in, how many DSP versions a certain tractusx-edc version should support and how we guarantee no changes are introduced to a currently supported version.
In my perspective there is no point in guaranteeing two distinct DSP versions are downwards compatible. To achieve this you would need to keep deprecated properties in newer versions, which you shouldn't need in the first place because you also support the previous (deprecated) version. In this sense, keeping up with deprecation is more simple because adopters can look for and remove deprecated DSP versions and not deprecated properties in recent versions.
Also, the requirement from CatenaX is that communication between two participants is not broken due to stack upgrades. If two participants communicate over a specific version of the DSP protocol, one of those participants can only upgrade its stack to a latter connector version IF this new version also supports the previous protocol version. I believe this is possible with the multi protocol support from the Connector. TractusX responsibility then is to define which DSP protocol versions have to be supported for each TractusX release.
In terms of testing, in my perspective tractusx-edc should only guarantee that the protocol data model never changes for an already supported version. This is not really testing for downward compatibility, but for consistency.
|
Nevertheless, many thanks @lgblaumeiser for pushing this decision record. |
|
Just leaving my 2 cents here :)
As mentioned, the
This is one of the reasons the migration guides include potential breaking changes and why I believe "sustaining" version for multiple iterations "indefinatly" a dangerous path, since we should never live in a idea that late adoption of a new version is great. If consistency with all versions are to be kept indeterminably than no one would bump versions.
I do not understood that this was being considered and still think it wasn't. It was the consistency between supported versions and not a "vanishing" from a simple one-sided bump. That said, really cool this discussion and helps define the tests; as long as supported versions are clearly defined, the tests should cover any of this concerns to happen. Regarding these:
IMO, is very hard to enforce any kind of manual check. The proposed tests should suffice, right? |
|
|
||
| ## Decision | ||
|
|
||
| DSP assets, like the catalog, which are forwarded directly to a caller through the management api, have to be kept downward compatible as long as the DSP version through which the asset is retrieved is supported. There is no compatibility requirement between two different DSP versions concerning such assets. |
There was a problem hiding this comment.
"DSP assets" don't exist.
Asset is a concept internal to the EDC domain, in DSP it could be reflected in the "Dataset" term (from DCAT spec)
|
|
||
| ## Decision | ||
|
|
||
| DSP assets, like the catalog, which are forwarded directly to a caller through the management api, have to be kept downward compatible as long as the DSP version through which the asset is retrieved is supported. There is no compatibility requirement between two different DSP versions concerning such assets. |
There was a problem hiding this comment.
yes, we need to be more specific, as here we're not talking about supporting a DSP version, but supporting the outcome of a specific EDC version based on a DSP version.
e.g. the EDC connector versions subsequent to 0.7.7 need to being able to operate with EDC connector at version 0.7.7 as well as other third party app that were built to operate with version 0.7.7.
Specifying that the connector version implemented by the 0.7.7 connector is a "special" DSP 0.8 (descibed here), not 100% compliant with the specs
it could be generalized as: once a new protocol version get supported by a connector, it should not change in the subsequent versions, or, better, the only way it could change is with the addition of a new version, through a new DSP endpoint with dedicated serdes logic.
|
|
||
| ## Rationale | ||
|
|
||
| DSP assets which are directly received by a caller of a management api endpoint is data that is transfered between two dataspace participants and creates a direct relationship between the calling application and the provider connector. As this is the case, the breaking change requirements of Catena-X has to be fulfilled. The requirement states that a consumer can continuously consume data from the provider without the need to be forced to update his system due to a change of the provider service stack. This requires that such assets must not change in a way, that existing properties vanish from the returned data. |
There was a problem hiding this comment.
| DSP assets which are directly received by a caller of a management api endpoint is data that is transfered between two dataspace participants and creates a direct relationship between the calling application and the provider connector. As this is the case, the breaking change requirements of Catena-X has to be fulfilled. The requirement states that a consumer can continuously consume data from the provider without the need to be forced to update his system due to a change of the provider service stack. This requires that such assets must not change in a way, that existing properties vanish from the returned data. | |
| DSP datasets which are obtained by a consumer third party app through the management api endpoint create a direct relationship between the calling application and the provider connector. As this is the case, the breaking change requirements of Catena-X has to be fulfilled. The requirement states that a consumer can continuously consume data from the provider without the need to be forced to update his system due to a change of the provider service stack. This requires that such assets must not change in a way, that existing properties vanish from the returned data. |
this need to be rephrased:
As this is the case
which case?
plus, a link to the "breaking change requirements of Catena-X" will be necessary
|
|
||
| DSP assets which are directly received by a caller of a management api endpoint is data that is transfered between two dataspace participants and creates a direct relationship between the calling application and the provider connector. As this is the case, the breaking change requirements of Catena-X has to be fulfilled. The requirement states that a consumer can continuously consume data from the provider without the need to be forced to update his system due to a change of the provider service stack. This requires that such assets must not change in a way, that existing properties vanish from the returned data. | ||
|
|
||
| As a consumer participant is capable to ensure the usage of a connector with a certain set of DSP versions supported, he is capable to use applications that are capable to support all potential data formats received by the different supported DSP versions. Therefore, the asset data models supported in two different DSP versions are not related and therefore no compatibility requirement is needed between those. |
There was a problem hiding this comment.
| As a consumer participant is capable to ensure the usage of a connector with a certain set of DSP versions supported, he is capable to use applications that are capable to support all potential data formats received by the different supported DSP versions. Therefore, the asset data models supported in two different DSP versions are not related and therefore no compatibility requirement is needed between those. | |
| As a consumer participant is capable to ensure the usage of a connector with a certain set of DSP versions supported, it is capable to use applications that are capable to support all potential data formats received by the different supported DSP versions. Therefore, the asset data models supported in two different DSP versions are not related and therefore no compatibility requirement is needed between those. |
looks a bit convoluted, could this be simplified? Like "changes between different protocol versions are expected"
|
|
||
| ## Approach | ||
|
|
||
| - The compatibility tests are enriched by tests that ensure the detection of changes in the corresponding DSP assets. |
There was a problem hiding this comment.
please explain the approach further
I totally agree and actually thought I expressed that in the text. Backward compatibility is only within a DSP version and there are requirements coming from Catena-X about how long a version is valid within the data space. Whether this requirement is realistic or not is another discussion. Backward compatibility with a new DSP version is provided by supporting the old version as well, using the multi-version support of the EDC.
Exactly, and we have to learn over time, how and potentially even how the requirement from Catena-X about the duration can be met.
Ok, for me this is downward compatibility between versions that support the same DSP protocol version concerning the implementation of the protocol version. That is downward compatibility on another layer compared to the compatibility between an EDC version that supports an older DSP version and an EDC supporting a newer DSP version but also providing means to communicate on the level of the older versions. Both are aspects of downward compatibility. |
|
Hi @bmg13 ,
There is a limitation to this specified by Catena-X, but in principle there is a requirement on the tools used in the Catena-X dataspace, I will add a link to that information.
That is not the question, it is defined, each implementation of a DSP version must not have breaking changes over its lifetime. If something has to be changed in a breaking way, it must be aligned with a DSP version to keep the expected behavior distinguishable.
I think we all agree, that adding properties are not considered as breaking changes and a tool must be implemented in a flexible way, i.e., it should ignore fields it does not need for its functionality. My understanding of the current cases is, that something have been removed from the returned catalog which was there in the earlier version. That was, what I meant with vanishing.
The test methodology I propose makes sense in cases, where it is really hard to create a correct expected object to which you can compare the data object you receive from the test object. In JavaScript the objects returned from some libraries are extremely large and you would not want to maintain the "correct" object by hand. So what they do, they record one test run, assuming that the returned object is right. Afterwards, they compare the test object against the previously recorded test object. This way, you will get an issue, whenever the test object implementation changes in a way, that the data object changes in any way. The question that needs to be answered is, whether the change is due to an intended change in the implementation or a regression done by accident. The manual check would involve to compare the changes of the previously recorded object from the currently returned object. The alternative is, that you define the minimum set of properties that you expect in the returned value and do a comparison that the data object returned from the test object is a superset of the minimum test data which is a valid approach but the comparison is a bit more difficult to implement. |
Signed-off-by: Lars Geyer-Blaumeiser <[email protected]>
|
WHAT
Decision Record on Downward Compatibility
WHY
As we had currently downward compatibility issues which lead to applications to fail to continue to work, a decision needs to be done about the expectation of the provided service implementation.