Prepare v3.0.0-beta1. (#1027)

Update CHANGELOG and version number for pre-release `3.0.0-beta1`.

---------

Co-authored-by: Luc Grosheintz <luc.grosheintz@gmail.com>
Co-authored-by: Matthias Wolf <matthias.wolf@epfl.ch>

CHANGELOG.md

@@ -1,4 +1,29 @@
 # Changes
+## Version 3.0.0-beta - 2024-07-16
+This version is a major one and is breaking some usage compare to v2.
+Read the migration guide from the documentation: https://bluebrain.github.io/HighFive/md__2home_2runner_2work_2_high_five_2_high_five_2doc_2migration__guide.html
+
+The minimum version for C++ has been moved to `C++14`.
+
+### Removed
+    - Removed `read(T*, ...)`, use explicit `read_raw(T*, ...)` for `Slice` or `Attribute`. (#928)
+    - Removed `FixedLenStringArray`, use any container with strings instead. (#932)
+    - Removed `FileDriver` and `MPIOFileDriver`, use file access properties instead. (#949)
+    - Removed default constructor for `Group` and `DataSet`. (#947, #948)
+    - Broadcasting have been removed. Use `squeeze` and `reshape` feature instead. (#992)
+    - `ObjectCreateProps` and `ObjectAccessProps` those don't map well to HighFive and are unused. (#1002)
+
+### New Features
+    - Added support for `std::span`. (#987)
+    - Added `squeezeMemSpace` and `reshapeMemSpace` for `Attribute` and `Slice` to reshape the memory space. (#991)
+    - Added `ProductSet` to select a Cartesian products of (generalized) slices. (#842)
+
+### Improvements
+    - Optimized chained hyperslab selection. (#1031)
+    - Type `T[N]` or `T[N][M]` will work better. (#929)
+    - `DataspaceType` is now an enum class for `dataspace_scalar` or `dataspace_null`. (#900)
+    - `File::AccessMode` is now an enum class. (#1020)
+
 ## Version 2.9.0 - 2024-01-25
 ### New Features
     - Add named ctors for scalar and null dataspaces. (#899)

CMakeLists.txt

@@ -2,6 +2,7 @@ cmake_minimum_required(VERSION 3.13)
 cmake_policy(VERSION 3.13)
 
 project(HighFive VERSION 3.0.0)
+set(HIGHFIVE_VERSION_PRERELEASE 1)
 
 # Configure HighFive
 # ------------------

README.md

@@ -46,6 +46,27 @@ It integrates nicely with other CMake projects by defining (and exporting) a Hig
 - xtensor (optional)
 - half (optional)
 
+### Versioning & Code Stability
+We use semantic versioning. Currently, we're preparing `v3` which contains a
+limited set of breaking changes required to eliminate undesireable behaviour or
+modernize outdated patterns. We provide a
+[Migration Guide](https://bluebrain.github.io/HighFive/md__2home_2runner_2work_2_high_five_2_high_five_2doc_2migration__guide.html),
+please report any missing or incorrect information to help others make the
+switch more easily.
+
+- `v2.x.y` are stable and any API breaking changes are considered bugs. There's
+  like not going to be very many releases of the `v2` line once `v3` is stable.
+
+- `v3.0.0-beta?` are pre-releases of `v3.0.0`. We predict that one more
+  breaking changes might happen: the string handling is confusing to some of the
+  maintainers and the default encoding is inconsistent (and will likely be made
+  consistent).
+
+  For codes that either use `std::string` when dealing with strings, or that
+  don't use strings with HDF5 at all, we don't currently have any additional
+  breaking changes planned for 3.0.0.
+
+
 ### Known flaws
 - HighFive is not thread-safe. At best it has the same limitations as the HDF5 library. However, HighFive objects modify their members without protecting these writes. Users have reported that HighFive is not thread-safe even when using the threadsafe HDF5 library, e.g., https://github.com/BlueBrain/HighFive/discussions/675.
 - Eigen support in core HighFive was broken until v3.0. See https://github.com/BlueBrain/HighFive/issues/532. H5Easy was not

include/highfive/H5Version.hpp

@@ -12,6 +12,9 @@
 #define HIGHFIVE_VERSION_MINOR 0
 #define HIGHFIVE_VERSION_PATCH 0
 
+// Undefined for regular releases.
+#define HIGHFIVE_VERSION_PRERELEASE 1
+
 /** \brief Concatenated representation of the HighFive version.
  *
  *  \warning The macro `HIGHFIVE_VERSION` by itself isn't valid C/C++.
@@ -30,4 +33,4 @@
  *
  *  \warning This macro only exists from 2.7.1 onwards.
  */
-#define HIGHFIVE_VERSION_STRING "3.0.0"
+#define HIGHFIVE_VERSION_STRING "3.0.0-beta1"

include/highfive/H5Version.hpp.in

@@ -12,6 +12,9 @@
 #define HIGHFIVE_VERSION_MINOR @PROJECT_VERSION_MINOR@
 #define HIGHFIVE_VERSION_PATCH @PROJECT_VERSION_PATCH@
 
+// Undefined for regular releases.
+#define HIGHFIVE_VERSION_PRERELEASE @HIGHFIVE_VERSION_PRERELEASE@
+
 /** \brief Concatenated representation of the HighFive version.
  *
  *  \warning The macro `HIGHFIVE_VERSION` by itself isn't valid C/C++.
@@ -30,4 +33,4 @@
  *
  *  \warning This macro only exists from 2.7.1 onwards.
  */
-#define HIGHFIVE_VERSION_STRING "@PROJECT_VERSION@"
+#define HIGHFIVE_VERSION_STRING "@PROJECT_VERSION@-beta@HIGHFIVE_VERSION_PRERELEASE@"

include/highfive/bits/H5Slice_traits.hpp

@@ -401,6 +401,7 @@ class HyperSlab {
 ///
 /// Note that the selections along each axis must be sorted and non-overlapping.
 ///
+/// \since 3.0
 class ProductSet {
   public:
     template <class... Slices>
@@ -461,6 +462,11 @@ class SliceTraits {
     ///
     Selection select(const ElementSet& elements) const;
 
+    ///
+    /// \brief Select a region consisting of a product of slices.
+    ///
+    /// \since 3.0
+    ///
     Selection select(const ProductSet& product_set) const;
 
     template <typename T>

tests/unit/tests_high_five_base.cpp

@@ -2537,6 +2537,12 @@ TEST_CASE("Version Numbers") {
                     std::to_string(patch);
 
     CHECK(version == expected);
+
+#if defined(HIGHFIVE_VERSION_PRERELEASE)
+    int prerelease = HIGHFIVE_VERSION_PRERELEASE;
+    expected += "-beta" + std::to_string(prerelease);
+#endif
+
     CHECK(HIGHFIVE_VERSION_STRING == expected);
 }