HDF5 Version Numbers and Branch Strategy

Versioning

The versioning policy follows the MAJOR.MINOR.PATCH Semantic Versioning Specification [1]. The most important rule is that we 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.

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.

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 only for 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 (e.g., 2.0.0-alpha.1, 2.0.0-beta) indicate that a version is unstable and may not satisfy the intended compatibility requirements of its associated regular version.

Build metadata (e.g., 2.0.0+20240717) may be appended with a plus sign. This metadata is ignored when determining version precedence.

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.x) when breaking changes are made to develop. Unlike our current branch/tag scheme, these maintenance branches should have a limited lifespan (1-2 releases, rather than multiple years).

Specifics:

• develop will continue to be the main development trunk
• v2.x, etc. will be the maintenance branch (like hdf5_1_14)
  • Only created when breaking changes are merged to develop
  • Kept in sync with develop via cherry-picking
  • Only one maintenance branch will be alive at one time
  • No longer maintained until the next release will be a major release
• v2.0, v2.1 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
  • Patch releases will be created by cherry picking bugfixes into this branch and creating a new release tag
  • Can be kept around for posterity

Tags

Tags for released versions will 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.