Skip to content

Semantic versioning update #5944

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 11 commits into
base: develop
Choose a base branch
from
+92 −39
Open

Semantic versioning update #5944

Show file tree
Hide file tree
Changes from 7 commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
9fa89ff
Add instruction to verify library version compliance with sematic
lrknox Oct 24, 2025
1bad14f
Committing clang-format changes
github-actions[bot] Oct 24, 2025
3430a90
Merge branch 'develop' of https://github.com/HDFGroup/hdf5 into seman…
lrknox Oct 24, 2025
de3e556
Merge branch 'semantic-versioning-update' of https://github.com/lrkno…
lrknox Oct 24, 2025
3f90c2e
Updates to provide:
lrknox Oct 29, 2025
2f0c195
Committing clang-format changes
github-actions[bot] Oct 29, 2025
ca59012
Update src/H5.c - fix typo
lrknox Oct 29, 2025
bfdb894
WILL_FAIL for the tcheck_version test doesn't need changing for release
lrknox Oct 30, 2025
ead3be0
Merge branch 'semantic-versioning-update' of https://github.com/lrkno…
lrknox Oct 30, 2025
1cbd5c6
Escape < in text with \ to avoid html parsing error.
lrknox Oct 30, 2025
cf2fd38
fix typo
lrknox Oct 31, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 14 additions & 10 deletions release_docs/RELEASE_PROCESS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,7 @@ For more information on the HDF5 versioning and backward and forward compatibili
3. Be sure to complete all four steps to update so numbers for each deployed lib file in the process described in config/lt_vers.am and check that the .so numbers for lib files in binaries correctly indicate compatibility status with the previous release.
4. Move all unresolved Milestone issues to the next release version in GitHub.
5. Verify that frozen code branch satisfies all existing regression test cases, and give the 'OK' to the release coordinator once all daily test configurations are passing as expected after the date of the code freeze. If there are failing tests after the code freeze date, coordinate with maintainers responsible for the failures to ensure that either the changes causing the failures are corrected or reverted.
6. Verify release branches for third-party software used: SZIP, ZLIB, and Plugins; and announce release versions to [email protected].
6. Verify released versions (latest) of third-party software used: SZIP, ZLIB, and Plugins; and announce release versions to [email protected].

### 5. Update Interface Version (Release Manager | Product Manager)
1. Verify interface additions, changes, and removals, and update the shared library interface version number.
Expand All @@ -71,9 +71,11 @@ For more information on the HDF5 versioning and backward and forward compatibili
6. Confirm the necessity of and approve of any interface-breaking changes. If any changes need to be reverted, task the developer who made the change to do so as soon as possible. If a change is reverted, return to the previous step and regenerate the compatibility report after the changes is made. Otherwise, continue to the next step.
7. Update the .so version numbers in the [config/lt_vers.am][u9] file in the support branch according to [libtool's library interface version](https://www.gnu.org/software/libtool/manual/libtool.html#Versioning) scheme.
- See [Updating version info (Libtool)](https://www.gnu.org/software/libtool/manual/html_node/Updating-version-info.html#Updating-version-info) for rules to help update library version numbers.
8. After the release branch has been created, run `./autogen.sh` to regenerate build system files on the release branch and commit the changes.
8. After the release branch has been created, run bin/process_source.sh to regenerate the H5E header files on the release branch, and commit the changes.

### 6. Prepare Release Branch (Release Manager)
### 6. Verify that HDF5 library version has been updated from the previous release according to [HDF5 versioning policy][u16], consistent with semantic versioning rules.

### 7. Prepare Release Branch (Release Manager)
1. Get the release branch ready for pre-release testing and packaging.
2. For all release preparation operations, the release coordinator will clone and push directly to canonical HDF5:
- `$ git clone ​https://github.com/HDFGroup/hdf5.git`
Expand All @@ -93,16 +95,17 @@ For more information on the HDF5 versioning and backward and forward compatibili
- `$ bin/h5vers -s X.Y.Z-{SR+1};`
- `$ git commit -m "Updated release preparation branch version number to X.Y.Z-{SR+1}"`
- `$ git push`
7. ** OBSOLETE CURRENTLY **
7. Remove 'WILL_FAIL "true"' line for minor version check in test/CMakeTests.cmake (currently line 662). Minor branches are considered incompatible for develop, but not for release branches.
8. ** OBSOLETE CURRENTLY **
Update default configuration mode
- `$ git checkout hdf5_X_Y_Z;`.
- Need to set option `HDF5_GENERATE_HEADERS` to `OFF`, currently in line 996 of [src/CMakeLists.txt][u11].
- (use `git status --ignored` to see the changes and `git add -f` to add all files. First delete any new files not to be committed, notably `src/H5public.h~`.)
- `$ git push with commit message listing change steps for creating release branch`
** END OBSOLETE CURRENTLY **
8. E-mail [email protected] to indicate that the code freeze on the release support branch (i.e. hdf5_X_Y) has been lifted and development on the next maintenance release can resume. The code freeze will remain in place on the release preparation branch (i.e. hdf5_X_Y_Z) indefinitely.
9. E-mail [email protected] to indicate that the code freeze on the release support branch (i.e. hdf5_X_Y) has been lifted and development on the next maintenance release can resume. The code freeze will remain in place on the release preparation branch (i.e. hdf5_X_Y_Z) indefinitely.

### 7. Perform Release Testing (Test Automation Team | Release Manager | Project Leads)
### 8. Perform Release Testing (Test Automation Team | Release Manager | Project Leads)
1. Verify that source and binary distributions of HDF5 are acceptable on all target operating environments.
2. Create a page on Confluence as a sub-page of the current release version's project collaboration page (see HDF5 Maintenance Releases) to document release testing results.
3. Document the test procedure that will be used for this release on the new sub-page.
Expand Down Expand Up @@ -164,7 +167,7 @@ For more information on the HDF5 versioning and backward and forward compatibili
19. Decide if another cycle of pre-release testing should occur based on the issue reports received and the actions taken during this cycle. If another round of testing is required (i.e. there were significant issues in pre-release testing which resulted in code changes), increment the subrelease version number and go back to step 7.2. If no further testing is required (i.e. no code changes were made and issues were documented as known issues, or code changes were trivial, unit tested, and exhaustive testing is unneeded), then proceed.


### 8. Finalize Release Notes (Release Manager)
### 9. Finalize Release Notes (Release Manager)
1. Perform a final review of release notes and ensure that any new changes made to the source, any new known issues discovered, and any additional tests run since the code freeze have been reflected in CHANGELOG.md and other appropriate in-source documentation files (INSTALL_*, etc.). (Refer to the sub-steps of step 3 for what to check).
2. Update the [CHANGELOG.md][u1] in the **support** branch (i.e. hdf5_X_Y) to remove entries in “Bugs fixed” and “New Features” sections and increment the version number for the following release (“Bug fixes since X.Y.Z” - occurs twice).
- `$ git checkout hdf5_X_Y`
Expand All @@ -173,7 +176,7 @@ For more information on the HDF5 versioning and backward and forward compatibili
- `$ git push`
3. Update Release Notes in **release** branch (Release Manager)

### 9. Package and Distribute Release (Release Manager)
### 10. Package and Distribute Release (Release Manager)
1. h5vers could run genparser, which can change the generated files if certain code files have been changed since the files generated by genparser were committed on the release branch. This should be checked by running `git status --ignored;`, then running genparser, then repeating `git status --ignored;`. If there are modified files from either git status command, they should be committed (or deleted if there are backup files or an autom4te.cache directory), and at least minimal testing should be done to see that the software is still good with the changes.
2. Set version for release, removing the subrelease string, initially `$ bin/h5vers -s X.Y.Z;`. Any subsequent patch releases will need the subrelease number.
3. Run `bin/release` (similar to 8.2) and commit all the changed files.
Expand All @@ -192,9 +195,9 @@ For more information on the HDF5 versioning and backward and forward compatibili
- Press "Run Workflow"
8. Release hdf5_plugins following the same steps.

### 10. Add the contents of the CHANGELOG.md file in the release code to the HISTORY-X_Y file in the **support** branch, just below the introductory lines at the top of the HISTORY file.
### 11. Add the contents of the CHANGELOG.md file in the release code to the HISTORY-X_Y file in the **support** branch, just below the introductory lines at the top of the HISTORY file.

### 11. Conduct Release Retrospective (Release Manager)
### 12. Conduct Release Retrospective (Release Manager)
1. Schedule time and solicit comments from retrospective
2. Identify issues and document them

Expand All @@ -212,3 +215,4 @@ For more information on the HDF5 versioning and backward and forward compatibili
[u13]: https://support.hdfgroup.org/documentation/hdf5/latest/api-compat-macros.html
[u14]: https://github.com/HDFGroup/hdf5/releases/tag/snapshot-1.14
[u15]: https://github.com/HDFGroup/hdf5/releases/tag/snapshot
[u16]: https://github.com/HDFGroup/hdf5/wiki/HDF5-Version-Numbers-and-Branch-Strategy
88 changes: 68 additions & 20 deletions src/H5.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -72,9 +72,14 @@ bool H5_PKG_INIT_VAR = false;
/* Library Private Variables */
/*****************************/

/* Library incompatible release versions, develop releases are incompatible by design */
static const unsigned VERS_RELEASE_EXCEPTIONS[] = {0};
static const unsigned VERS_RELEASE_EXCEPTIONS_SIZE = 1;
/* Library known incompatible minor versions; develop releases are incompatible
* by design. 999 is entered for testing an exception as a minor version that
* will never occur. Any released minor version found to be truly incompatible
* (this should never happen) should be added to the list with 999. 999 alone
* in the list indicates that there are no incompatible minor versions. */
static const unsigned VERS_MINOR_EXCEPTIONS[] = {999};
/* The size should be set to the number of minor version exceptions in the list. */
static const unsigned VERS_MINOR_EXCEPTIONS_SIZE = 1;

/* Library init / term status (global) */
bool H5_libinit_g = false; /* Library hasn't been initialized */
Expand Down Expand Up @@ -806,8 +811,8 @@ H5get_libversion(unsigned *majnum /*out*/, unsigned *minnum /*out*/, unsigned *r
* version numbers compiled into the library.
*
* Within major.minor.release version, the expectation
* is that all release versions are compatible, exceptions to
* this rule must be added to the VERS_RELEASE_EXCEPTIONS list.
* is that all minor versions are compatible, exceptions to
* this rule must be added to the VERS_MINOR_EXCEPTIONS list.
*
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more. 

 *              Within major.minor.release version numbering:
 *              - Major version must match exactly (breaking changes)
 *              - Minor versions within the same major are backward compatible
 *              - Specific minor versions (e.g., develop=0) can be marked as
 *                incompatible in VERS_MINOR_EXCEPTIONS list
 *              - Release (patch) versions are always compatible (not checked)

* Return: Success: SUCCEED
* Failure: abort()
Expand All @@ -823,15 +828,24 @@ H5get_libversion(unsigned *majnum /*out*/, unsigned *minnum /*out*/, unsigned *r
"linked with a different version of static or shared HDF5 library.\n" \
"You should recompile the application or check your shared library related\n" \
"settings such as 'LD_LIBRARY_PATH'.\n"
#define RELEASE_MISMATCH_WARNING \
"Warning! ***HDF5 library release mismatched error***\n" \
#define MINOR_VERSION_MISMATCH_WARNING \
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

semantic versioning says minor versions should be compatible.

"Warning! ***HDF5 library minor version mismatch (incompatible version detected)***\n"
    "The HDF5 header or library version used is marked as incompatible.\n"
    "This typically indicates development/unstable versions are being mixed.\n"

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes. We should never have occasion to use the exceptions.

"Warning! ***HDF5 library minor version mismatched error***\n" \
"The HDF5 header files used to compile this application are not compatible with\n" \
"the version used by the HDF5 library to which this application is linked.\n" \
"Data corruption or segmentation faults may occur if the application continues.\n" \
"This can happen when an application was compiled by one version of HDF5 but\n" \
"linked with an incompatible version of static or shared HDF5 library.\n" \
"You should recompile the application or check your shared library related\n" \
"settings such as 'LD_LIBRARY_PATH'.\n"
#define MINOR_VERSION_FORWARD_COMPATIBLE_WARNING \
"Warning! ***HDF5 library minor version forward compatibility error***\n" \
"The HDF5 header files used to compile this application are from a newer\n" \
"version of the HDF5 library than the one to which this application is linked.\n" \
"Data corruption or segmentation faults may occur if the application continues.\n" \
"This can happen when an application was compiled by a newer version of HDF5 but\n" \
"linked with an older version of static or shared HDF5 library.\n" \
"You should recompile the application or check your shared library related\n" \
"settings such as 'LD_LIBRARY_PATH'.\n"

static herr_t
H5_check_version(unsigned majnum, unsigned minnum, unsigned relnum)
Expand All @@ -841,8 +855,9 @@ H5_check_version(unsigned majnum, unsigned minnum, unsigned relnum)
static bool checked = false; /* If we've already checked the version info */
static unsigned int disable_version_check = 0; /* Set if the version check should be disabled */
static const char *version_mismatch_warning = VERSION_MISMATCH_WARNING;
static const char *release_mismatch_warning = RELEASE_MISMATCH_WARNING;
herr_t ret_value = SUCCEED; /* Return value */
static const char *minor_version_mismatch_warning = MINOR_VERSION_MISMATCH_WARNING;
static const char *minor_version_forward_compatible_warning = MINOR_VERSION_FORWARD_COMPATIBLE_WARNING;
herr_t ret_value = SUCCEED; /* Return value */

FUNC_ENTER_NOAPI_NOINIT_NOERR

Expand All @@ -860,8 +875,8 @@ H5_check_version(unsigned majnum, unsigned minnum, unsigned relnum)
disable_version_check = (unsigned int)strtol(s, NULL, 0);
}

/* H5_VERS_MAJOR and H5_VERS_MINOR must match */
if (H5_VERS_MAJOR != majnum || H5_VERS_MINOR != minnum) {
/* H5_VERS_MAJOR must match */
if (H5_VERS_MAJOR != majnum) {
switch (disable_version_check) {
case 0:
fprintf(stderr, "%s%s", version_mismatch_warning,
Expand Down Expand Up @@ -896,17 +911,17 @@ H5_check_version(unsigned majnum, unsigned minnum, unsigned relnum)
break;
} /* end switch */

} /* end if (H5_VERS_MAJOR != majnum || H5_VERS_MINOR != minnum) */
} /* end if (H5_VERS_MAJOR != majnum) */

/* H5_VERS_RELEASE should be compatible, we will only add checks for exceptions */
/* Library develop release versions are incompatible by design */
if (H5_VERS_RELEASE != relnum) {
for (unsigned i = 0; i < VERS_RELEASE_EXCEPTIONS_SIZE; i++) {
/* H5_VERS_MINOR should be compatible, we will only add checks for exceptions */
/* Library develop minor versions are incompatible by design */
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For semantic versioning, minor version increments should be backward compatible, so I'm not sure why the PR treats minor version differences as exceptions that need special handling

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The logic treats ALL minor version differences as potential incompatibilities unless the exceptions list is empty. This is backwards from semantic versioning logic.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The logic is there because of history mostly. The 1.10 version had incompatible versions because of incorrect programming. The normal expected use is that all minor versions are compatible.

Copy link
Collaborator

@brtnfld brtnfld Oct 24, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Right, we want to update the schema for semantic versioning,

As is the PR, it does not distinguish between:
2.0.x -> 2.1.x is ok
2.1.x -> 2.-.x should warn/fail

it should be
(1) major must match
(2) minor version backward compatibility check
2a, check if either version is in the incompatible list (e.g., develop)

if (H5_VERS_MINOR != minnum) {
for (unsigned i = 0; i < VERS_MINOR_EXCEPTIONS_SIZE; i++) {
/* Check for incompatible headers or incompatible library */
if (VERS_RELEASE_EXCEPTIONS[i] == relnum || VERS_RELEASE_EXCEPTIONS[i] == H5_VERS_RELEASE) {
if (VERS_MINOR_EXCEPTIONS[i] == minnum || VERS_MINOR_EXCEPTIONS[i] == H5_VERS_MINOR) {
switch (disable_version_check) {
case 0:
fprintf(stderr, "%s%s", release_mismatch_warning,
fprintf(stderr, "%s%s", minor_version_mismatch_warning,
"You can, at your own risk, disable this warning by setting the environment\n"
"variable 'HDF5_DISABLE_VERSION_CHECK' to a value of '1'.\n"
"Setting it to 2 or higher will suppress the warning messages totally.\n");
Expand All @@ -924,7 +939,7 @@ H5_check_version(unsigned majnum, unsigned minnum, unsigned relnum)
"%s'HDF5_DISABLE_VERSION_CHECK' "
"environment variable is set to %d, application will\n"
"continue at your own risk.\n",
release_mismatch_warning, disable_version_check);
minor_version_mismatch_warning, disable_version_check);
/* Mention the versions we are referring to */
fprintf(stderr, "Headers are %u.%u.%u, library is %u.%u.%u\n", majnum, minnum, relnum,
(unsigned)H5_VERS_MAJOR, (unsigned)H5_VERS_MINOR, (unsigned)H5_VERS_RELEASE);
Expand All @@ -938,7 +953,40 @@ H5_check_version(unsigned majnum, unsigned minnum, unsigned relnum)

} /* end for */

} /* end if (H5_VERS_RELEASE != relnum) */
/* Check for forward compatibility usage. */
if (H5_VERS_MINOR > minnum) {
switch (disable_version_check) {
case 0:
fprintf(stderr, "%s%s", minor_version_forward_compatible_warning,
"You can, at your own risk, disable this warning by setting the environment\n"
"variable 'HDF5_DISABLE_VERSION_CHECK' to a value of '1'.\n"
"Setting it to 2 or higher will suppress the warning messages totally.\n");
/* Mention the versions we are referring to */
fprintf(stderr, "Headers are %u.%u.%u, library is %u.%u.%u\n", majnum, minnum, relnum,
(unsigned)H5_VERS_MAJOR, (unsigned)H5_VERS_MINOR, (unsigned)H5_VERS_RELEASE);

/* Bail out now. */
fputs("Bye...\n", stderr);
abort();
case 1:
/* continue with a warning */
/* Note that the warning message is embedded in the format string.*/
fprintf(stderr,
"%s'HDF5_DISABLE_VERSION_CHECK' "
"environment variable is set to %d, application will\n"
"continue at your own risk.\n",
minor_version_forward_compatible_warning, disable_version_check);
/* Mention the versions we are referring to */
fprintf(stderr, "Headers are %u.%u.%u, library is %u.%u.%u\n", majnum, minnum, relnum,
(unsigned)H5_VERS_MAJOR, (unsigned)H5_VERS_MINOR, (unsigned)H5_VERS_RELEASE);
break;
default:
/* 2 or higher: continue silently */
break;
} /* end switch */
}

} /* end if (H5_VERS_MINOR != minnum) */

/* Indicate that the version check has been performed */
checked = true;
Expand Down
7 changes: 4 additions & 3 deletions test/CMakeTests.cmake
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -654,6 +654,8 @@ set_tests_properties (H5TEST-tcheck_version-major PROPERTIES
if ("H5TEST-tcheck_version-major" MATCHES "${HDF5_DISABLE_TESTS_REGEX}")
set_tests_properties (H5TEST-tcheck_version-major PROPERTIES DISABLED true)
endif ()
# The minor version test will test version 999 and always fail because it's listed in
# VERS_MINOR_EXCEPTIONS. With WILL_FAIL "true" the failing test passes.
add_test (NAME H5TEST-tcheck_version-minor COMMAND $<TARGET_FILE:tcheck_version> "-tm")
set_tests_properties (H5TEST-tcheck_version-minor PROPERTIES
WORKING_DIRECTORY ${HDF5_TEST_BINARY_DIR}/H5TEST
Expand All @@ -663,13 +665,12 @@ set_tests_properties (H5TEST-tcheck_version-minor PROPERTIES
if ("H5TEST-tcheck_version-minor" MATCHES "${HDF5_DISABLE_TESTS_REGEX}")
set_tests_properties (H5TEST-tcheck_version-minor PROPERTIES DISABLED true)
endif ()
# release + 1 should pass on non-develop branches
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

#release + 1 should always PASS (release version not checked in semver)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Right that is why we do not need to check this condition.

Copy link
Collaborator

@brtnfld brtnfld Oct 27, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suggested revising the comment

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Comment revised to "release + 1 should always pass (not checked)."

# release + 1 should always pass (not checked)
add_test (NAME H5TEST-tcheck_version-release COMMAND $<TARGET_FILE:tcheck_version> "-tr")
set_tests_properties (H5TEST-tcheck_version-release PROPERTIES
WORKING_DIRECTORY ${HDF5_TEST_BINARY_DIR}/H5TEST
ENVIRONMENT "${CROSSCOMPILING_PATH}"
WILL_FAIL "true"
)
)
if ("H5TEST-tcheck_version-release" MATCHES "${HDF5_DISABLE_TESTS_REGEX}")
set_tests_properties (H5TEST-tcheck_version-release PROPERTIES DISABLED true)
endif ()
Expand Down
Loading