Versioning of packages doesn't follow the semantic versioning specification

[gkarat]

Hello, I recently worked with one of the API client - @redhat-cloud-services/host-inventory-client and the Inventory application (which is a consumer of this client). While I was upgrading the client dependency version from 1.0.96 to 1.0.109, I found out that the application has got broken. Debugging the problem, I realized that the HostsApi's apiHostGetHostList function parameters were modified (specifically, the order has changed, and the wrong parameters were sent by the consumer app).

I managed to fix this and this is OK to have client interface changes, however, I would love to see such breaking changes documented and reflected with the help of versioning of the package. Just incrementing the patch version is not correct, because I would expect the increment of the major version if a broken change introduced to the interface.

Just for evidence and illustration, this is the commit that changed the function parameters: b9b6839#diff-a9f2cff91e34cf8e2a01709fba111c82cc0e22f1f5f3782607c7f789beb189aeR1907.

[karelhala]

@gkarat the problem lies on the API team itself, we are simply taking what's in the apiSpec and turning it into JS client. In the past I was thinking about a way how to bypass this, however it makes sence to change the order of attributes if something has been added. Usually what we did for inventory was upgrading the version, checking if everything works and shuffling around the parameters.

[bastilian]

@karelhala I believe the hardest part is to identify if the arguments are in the correct position and sometimes even when they are incorrect it is possible that the API cal still works and returns results that do look vaguely correct. Would it be possible to use an object (basically named arguments) for api functions to pass instead?

[karelhala]

@bastilian I was playing with the idea of object which would spread as well, but the oficial documentation for the tools we are using does not support it. We have a master thesis prepared for this semestr which would basically create new JS client generator.