Comment 29 for bug 1717040

Hi Robie

As far as I can tell, it is much more likely that an application expecting zstd >=v1.0.0 will break, most likely at link stage, and maybe at run stage, when provided with v0.5.1 instead.
The other way round should be less problematic : applications expecting to work with v0.5.1 should still work with v.1.3.1.

The reason is :
All symbols defined in v0.5.1 are also present in the "stable" section of v1.3.1.

For reference, here is the API for v0.5.1 : https://github.com/facebook/zstd/blob/v0.5.1/lib/zstd.h
and here is the API for v1.3.1 : https://github.com/facebook/zstd/blob/v1.3.1/lib/zstd.h

The major counter example is the streaming API.
This one used to be available in a separate package :
https://github.com/facebook/zstd/blob/v0.5.1/lib/zbuff.h
It is clearly labelled experimental, hence does not provide any API stability guarantee.

Nonetheless, in v1.3.1, this API is still available here :
https://github.com/facebook/zstd/blob/v1.3.1/lib/deprecated/zbuff.h
It is the exact same API, defining the same symbols.
What has changed is that this API is now branded "deprecated", which means it will generate deprecation warnings during compilation (except if these warnings are explicitly disabled, using typically -Wno-deprecated-declarations for gcc, or the custom macro ZBUFF_DISABLE_DEPRECATE_WARNINGS).

The deprecation warnings include comments to invite users to migrate towards the new "stable" streaming API, defined here : https://github.com/facebook/zstd/blob/v1.3.1/lib/zstd.h#L248
Of course, this is only useful for developers.