Change Policy

*** DRAFT ***

API and File Format Changes

We strive to maintain forward and backward compatibility in the HDF5 library across releases:

File Format Considerations

• New versions of the library should be able to open HDF5 files written using an older format
• Old versions of the library should not crash when encountering new file objects
• New versions of the library should be able to create and modify HDF5 files using older file formats

API and Breaking Changes

• We strive to behave according to the principles of semantic versioning
• Changes to existing API calls or other breaking changes can only go into a new MAJOR release
• New API calls or other non-breaking changes can be added to a MINOR release
• We rarely do a patch release, but when we do, those only contain specific bug fixes
• In HDF5 2.0.0, we will fix the versioning number scheme
• We attempt to provide backward-compatible API shims when we modify existing API calls
• Semantics is a part of "the API" and should be maintained with the same care we have for function signatures
• Buggy behavior is not part of the API and can be fixed/change at any time

Non-API changes

We make no guarantees about maintaining support for non-library things (though we try to minimize disruption):

• Support for specific platforms or compilers, including language standards
• Support for build systems and options

Change Communication

When we envision making a change that could impact existing users, we will make our best effort to engage with the community.

We will:

• Make a sticky post on the HDF Group forum in the HDF5 channel at least one month before making a change
• Create a discussion issue on GitHub
• Mention the issue and post in the HDF Group newsletter while the sticky post is up
• Bring the issue up in the HDF5 Working Group meeting at least once
• Bring the issue up at at least one Call the Doctor session