Document breaking change on the rename to sdk-client-v2

[rvanlaak]

When upgrading the Commercetools SDK to new major versions, there was an undocumented breaking change because it was not documented that the sdk-client was renamed to sdk-client-v2.

The problem is not with the breaking change or the upgrade, but after checking the client CHANGELOG.md there was no trace of a note about this breaking change.

In order to help others with upgrading, it would be good to add a note over there on the release that introduced this breaking change (read: the rename).

It seems that upgrading is as simple as changing the import. Is that correct?

[jenschude]

It's a good question if it's a breaking change as the old client package was written in NodeJS. The v2 version is now written in Typescript and includes all necessary middlewares directly. Also the v2 version should mostly work as drop in replacement.

Nevertheless we may add the description from the release note to the changelog: https://github.com/commercetools/commercetools-sdk-typescript/releases/tag/%40commercetools%2Fsdk-client-v2%401.0.0

[rvanlaak]

Every time when you have to make a change to your codebase when upgrading, that is a breaking change right? The update breaks the code.

Don't get me wrong, it is a major update (from v1 to v2), so it is no problem that the change is there. I've created this issue so we can properly document that people should actually change the import, and that that is the only thing they will have to do.

Documenting any type of breaking changes (even the small ones like this one) gives engineers confidence to do upgrades over postponing updates when they are uncertain about the possible breaking changes a package might bring.

[jenschude]

I totally understand your point. Just wanted to say the change itself is not necessary as v1 & v2 client are valid to be used using the SDK. We advise to use the v2 one as it brings the type safety to your codebase. For users of the SDK in NodeJS it's not necessarily needed.