README.md
1HDF5
2====
3
4The `itkhdf5` subdirectory contains a reduced distribution of the hdf5 source
5tree with only the library source code and [CMake] build system. It is not a
6submodule; the actual content is part of our source tree and changes can be
7made and committed directly.
8
9We update from upstream using Git's "subtree" merge strategy. A special branch
10contains commits of upstream hdf5 snapshots and nothing else. No Git ref points
11explicitly to the head of this branch, but it is merged into our history.
12
13Update hdf5 from upstream as follows. Create a local branch to explicitly
14reference the upstream snapshot branch head:
15
16```sh
17 $ git branch hdf5-upstream 5d643456
18```
19
20Use a temporary directory to checkout the branch:
21
22```sh
23 $ mkdir hdf5-tmp
24 $ cd hdf5-tmp
25 $ git init
26 $ git pull .. hdf5-upstream
27 $ rm -rf *
28```
29
30Now place the (reduced) hdf5 content in this directory. Edit and run the script
31
32```sh
33 $ ../Modules/ThirdParty/HDF5/src/DownloadAndReduceUpstream.sh
34```
35
36to extract the content from the upstream SVN repository. Then run the following
37commands to commit the new version. Substitute the appropriate date and version
38number:
39
40```sh
41 $ cp -a hdf5-*-reduced/* .
42 $ rm -rf hdf5-*
43
44 $ git add -u
45 $ git add .
46
47 $ GIT_AUTHOR_NAME='HDF Group' \
48 $ GIT_AUTHOR_EMAIL='hdf-forum@hdfgroup.org' \
49 $ GIT_AUTHOR_DATE='2016-07-24 23:06:03 -0400' \
50 $ git commit -m 'ENH: hdf5 1.8.17-r30218 (reduced)'
51```
52
53Then push the changes back up to the main repository:
54
55```sh
56 $ git push .. HEAD:hdf5-upstream
57 $ cd ..
58 $ rm -rf hdf5-tmp
59```
60
61Create a topic in the main repository on which to perform the update:
62
63```sh
64 $ git checkout -b update-hdf5 master
65```
66
67Merge the `hdf5-upstream` branch as a subtree:
68
69```sh
70 $ git merge -s recursive -X subtree=Modules/ThirdParty/HDF5/src/itkhdf5 \
71 hdf5-upstream
72```
73
74If there are conflicts, resolve them and commit. Build and test the tree.
75Commit any additional changes needed to succeed.
76
77Finally, run
78
79```sh
80 $ git rev-parse --short=8 hdf5-upstream
81```
82
83to get the commit from which the `hdf5-upstream` branch must be started on the
84next update. Edit the `git branch hdf5-upstream` line above to record it, and
85commit this file.
86
87
88
89[CMake]: https://cmake.org/
90