too much API breakage between releases - mandatory use of semantic versioning


HDF5 v1.12 should probably be better called HDF6 at this stage.

The breaking API changes between minor HDF5 releases (eg. 1.8, 1.10, 1.12) are rather disconcerting, even taking into the various brittle pre-processor tricks used as “workarounds”. Stuff like H5_USE_110_API is in the end just a hack, papering over the unwarranted breakage.

The point of HDF is to be a boring storage abstraction, where by “boring” I mean stable. HDF5 is definitely not boring, which decreases its value and utility.

The use of semantic versioning to label HDF releases would help in this regard immensely. Minor releases such as v1.12 should not be introducing any kind of API breaks. Such breaks are better communicated by bumping the major version number, for example HDF6, HDF7, etc.

The current approach of API breakage between minor releases is causing all sorts of issues. Examples:

TLDR: I would suggest that the HDF5 developers be made explicitly aware that public API breaks in HDF5 releases are not exactly conducive to productivity. It would be useful to properly communicate such changes via an increase in the major version number, for example HDF6. The current practice of updating “HDF5” with incompatible changes is overall counter-productive, and a negative net contribution.


I believe the 5 in HDF5 refers to the file format and not the library release version. Semantic versioning may well be useful here, but you’re looking the wrong label.