Add HDF5 2.0.0 Library Migration Guide

[gheber]

A migration guide for the rest of us.

---

Important

Adds a detailed migration guide for upgrading to HDF5 2.0.0, focusing on compatibility, upgrade strategies, and debunking myths.

• Migration Guide:
  • Adds HDF5_Library_2.0.0_Migration_Guide.md detailing the upgrade process to HDF5 2.0.0.
  • Covers file, API, and ABI compatibility, emphasizing the use of API Compatibility Macros.
  • Provides a decision tree and checklists for pre-, during-, and post-upgrade phases.
• Upgrade Strategies:
  • Recommends "Zero/low code-change" migration as a starting point.
  • Discusses targeted modernization and "New API only" hardening.
• Examples and Myths:
  • Includes examples for rebuilding applications, handling signature changes, and ensuring backward compatibility.
  • Debunks common myths about HDF5 2.0.0 upgrade impacts.

^{This description was created by for 9fa3c1f. You can customize this summary. It will automatically update as commits are pushed.}

[hyoklee]

What does its XML output mode is deprecated mean? XML output still works and doesn't show any deprecation warning or error message:

nene-[12:56am]~/src/hdf5.HDFGroup/build>./bin/h5dump --xml ~/data/h5/ATL15_A2_0\
328_01km_005_01.nc
<?xml version="1.0" encoding="UTF-8"?>
<hdf5:HDF5-File xmlns:hdf5="http://hdfgroup.org/HDF5/XML/schema/HDF5-File.xsd" \
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http:\
//hdfgroup.org/HDF5/XML/schema/HDF5-File http://www.hdfgroup.org/HDF5/XML/schem\
a/HDF5-File.xsd">
<hdf5:RootGroup OBJ-XID="xid_48" H5Path="/">
   <hdf5:Attribute Name="Conventions">
      <hdf5:Dataspace>
         <hdf5:ScalarDataspace />
...

[gheber]

https://github.com/HDFGroup/hdf5/blob/2.0.0/release_docs/CHANGELOG.md

The h5dump XML option is deprecated and will be removed in a future release. The XML output format has not been maintained and is not up-to-date with the latest features of HDF5.

[hyoklee]

Use either 2.0 or 2.0.0 consistently throughout the document.

[gheber]

Updated.

[hyoklee]

Nothing is done for xml deprecation for 2.0.0 (E.g., forum announcement / H5WG discussion) but it's OK to give a heads up for 2.0.0 users.

[brtnfld]

Clarify:

HDF5 2.0.0 introduces new APIs and behavioral changes. While standard user APIs are preserved via compatibility macros, a small set of advanced developer APIs (specifically in the VOL layer) were removed entirely