HDF5 Version Numbers and Branch Strategy

Versioning

The versioning policy follows the MAJOR.MINOR.PATCH Semantic Versioning Specification [1]. The most important rule regarding HDF5 is to increment the MAJOR version for any API-breaking change or for any modification to the HDF5 file format itself.

Defining Backward Compatibility

The backward compatibility is defined as follows:

• API Backward Compatibility (Source Level): User source code that compiles against version X.Y.Z of the library MUST compile without modification against any later version X.A.B where A >= Y. This means no functions or public data structures are removed or renamed.
• ABI Backward Compatibility (Binary Level): An application dynamically linked against version X.Y.Z of the shared library MUST run without recompilation against any later version X.A.B where A >= Y. This is a stricter requirement that prohibits changes to function signatures or the memory layout of public data structures.
• File Format Backward Compatibility: Files created by version X.Y.Z of the library MUST be readable in their entirety by any version X.A.B, with no restrictions on A and B.

Versioning Policy Definition 📝

The HDF5 version number consists of three parts: MAJOR.MINOR.PATCH

• MAJOR: Increased for incompatible changes, including API modifications and any changes to the HDF5 file format.
• MINOR: Increased when new, backward-compatible features are added to the API.
• PATCH: Increased for backward-compatible bug fixes.

Rules for Incrementing Versions

💥 MAJOR Version

The MAJOR version increases whenever there is a change that breaks backward compatibility. This includes:

• File Format Changes: Any modification to the HDF5 file format specification. This creates a fundamental data-level incompatibility.
• API/ABI Incompatibility: Any change that breaks either API or ABI backward compatibility. This includes altering function signatures, removing public functions, or changing the layout of public data structures. This includes new versions of public functions, since newly versioning a function changes the ABI. For consistency, this also includes new versions of previously versioned functions, even though this does not change the existing interfaces in the API or ABI.

When the MAJOR version increases, the MINOR and PATCH versions MUST be reset to 0.

✨ MINOR Version

The MINOR version is increased for new, backward-compatible features. A MINOR release MUST keep both API and ABI backward compatibility with previous MINOR releases of the same MAJOR version. This enables users to upgrade their applications without needing to recompile them.

The MINOR version is increased when:

1. New functions are added to the public API.
2. Existing features are marked as deprecated.

When the MINOR version is increased, the PATCH version MUST be reset to 0.

🐛 PATCH Version

The PATCH version is increased for releases that contain only backward-compatible bug fixes. A PATCH release MUST preserve both API and ABI backward compatibility. This includes internal fixes for correctness, security, or performance that do not change the public interface.

---

Pre-releases and Build Metadata

Under SemVer 2.0.0, we may use pre-release tags and build metadata.

• Pre-release versions should be formatted by appending a - followed by a number 'X', resulting in 'MAJOR.MINOR.PATCH-X' (e.g., 2.0.0-1, 2.0.0-2).

Branch/Tag Strategy

Branches

Going forward, we will try to come as close as possible to trunk-based development. This means that, whenever possible, we will create our release branches off of develop. We will only create a maintenance branch (e.g., v3) when breaking changes are made to develop. Unlike our current branch/tag scheme, these maintenance branches will only stick around until the next major release.

Specifics:

• develop will continue to be the main development trunk
• v2, etc. will be the maintenance branch (like hdf5_1_14)
  • Only created when a change that requires a new major version is merged to develop
  • Kept in sync with develop via cherry-picking
  • Only one maintenance branch will be alive at one time, once the next major version is released it becomes inactive
• v2.0.0, v2.0.1, v2.1.0 etc. will be release branches (like hdf5_1_14_5)
  • The purpose is to provide stability as we prepare the release
  • Created shortly before a release
  • Not kept in sync with parent branch - just cherry picks of anything important for the release
  • Tags are created from this branch when we release
  • Minor and patch releases are handled the same here, if there is a change that requires a minor release, bump that number and set the patch number to 0, otherwise just bump the patch number
  • Can be kept around for posterity, but will be inactive after the associated release

Tags

Tags for released versions will similarly be named v<major>.<minor>.<patch>. We will keep old tags around for posterity, but will also create new tags for all released versions of HDF5 that use the vx.y.z scheme. This will make it easier to check out various versions of the library.

Example

• 2.0.0 is released
• All development done only in develop:
• It is time to release
  • Since there were only bugfixes it is a patch release, create v2.0.1 branch from develop, run release tasks, create v2.0.1 tag and release it
• Continue development in develop
• There is a change merged to develop that requires a new major version. Create v2 branch from develop.
• Development continues in develop, but from this point, all changes that don't require a new major version or depend on code only in develop must be cherry picked from develop to v2
• It is time to release
  • Since there was an API addition in v2 since 2.0.1 it is a minor release, create v2.1.0 branch from v2, run release tasks, create v2.1.0 tag and release it
• It is decided that the next release will be a major release, so v2 is made inactive
• Continue development only in develop
• It is time to release
  • Create v3.0.0 branch from develop, run release tasks, create v3.0.0 tag and release it