philipp/hdf5
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

[svn-r2482] Bringing "HDF5 Technical Notes" into development branch (from R1.2 branch)

Browse Source
This commit is contained in:
Frank Baker
2000-08-25 12:42:24 -05:00
parent 3ff571ab58
commit 2e8cd59163
35 changed files with 4108 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

137
doc/html/TechNotes/Version.html Normal file
View File

@@ -0,0 +1,137 @@
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<html>
<head>
<title>Version Numbers</title>
</head>
<body>
<h1>HDF5 Release Version Numbers</h1>
<h2>1. Introduction</h2>
<p>The HDF5 version number is a set of three integer values
written as either <code>hdf5-1.2.3</code> or <code>hdf5 version
1.2 release 3</code>.
<p>The <code>5</code> is part of the library name and will only
change if the entire file format and library are redesigned
similar in scope to the changes between HDF4 and HDF5.
<p>The <code>1</code> is the <em>major version number</em> and
changes when there is an extensive change to the file format or
library API. Such a change will likely require files to be
translated and applications to be modified. This number is not
expected to change frequently.
<p>The <code>2</code> is the <em>minor version number</em> and is
incremented by each public release that presents new features.
Even numbers are reserved for stable public versions of the
library while odd numbers are reserved for developement
versions. See the diagram below for examples.
<p>The <code>3</code> is the <em>release number</em>. For public
versions of the library, the release number is incremented each
time a bug is fixed and the fix is made available to the public.
For development versions, the release number is incremented more
often (perhaps almost daily).
<h2>2. Abbreviated Versions</h2>
<p>It's often convenient to drop the release number when referring
to a version of the library, like saying version 1.2 of HDF5.
The release number can be any value in this case.
<h2>3. Special Versions</h2>
<p>Version 1.0.0 was released for alpha testing the first week of
March, 1998. The developement version number was incremented to
1.0.1 and remained constant until the the last week of April,
when the release number started to increase and development
versions were made available to people outside the core HDF5
development team.
<p>Version 1.0.23 was released mid-July as a second alpha
version.
<p>Version 1.1.0 will be the first official beta release but the
1.1 branch will also serve as a development branch since we're
not concerned about providing bug fixes separate from normal
development for the beta version.
<p>After the beta release we rolled back the version number so the
first release is version 1.0 and development will continue on
version 1.1. We felt that an initial version of 1.0 was more
important than continuing to increment the pre-release version
numbers.
<h2>4. Public versus Development</h2>
<p>The motivation for separate public and development versions is
that the public version will receive only bug fixes while the
development version will receive new features. This also allows
us to release bug fixes expediently without waiting for the
development version to reach a stable state.
<p>Eventually, the development version will near completion and a
new development branch will fork while the original one enters a
feature freeze state. When the original development branch is
ready for release the minor version number will be incremented
to an even value.
<p>
<center>
<img alt="Version Example" src="version.gif">
<br><b>Fig 1: Version Example</b>
</center>
<h2>5. Version Support from the Library</h2>
<p>The library provides a set of macros and functions to query and
check version numbers.
<dl>
<dt><code>H5_VERS_MAJOR</code>
<dt><code>H5_VERS_MINOR</code>
<dt><code>H5_VERS_RELEASE</code>
<dd>These preprocessor constants are defined in the public
include file and determine the version of the include files.
<br><br>
<dt><code>herr_t H5get_libversion (unsigned *<em>majnum</em>, unsigned
*<em>minnum</em>, unsigned *<em>relnum</em>)</code>
<dd>This function returns through its arguments the version
numbers for the library to which the application is linked.
<br><br>
<dt><code>void H5check(void)</code>
<dd>This is a macro that verifies that the version number of the
HDF5 include file used to compile the application matches the
version number of the library to which the application is
linked. This check occurs automatically when the first HDF5
file is created or opened and is important because a mismatch
between the include files and the library is likely to result
in corrupted data and/or segmentation faults. If a mismatch
is detected the library issues an error message on the
standard error stream and aborts with a core dump.
<br><br>
<dt><code>herr_t H5check_version (unsigned <em>majnum</em>,
unsigned <em>minnum</em>, unsigned <em>relnum</em>)</code>
<dd>This function is called by the <code>H5check()</code> macro
with the include file version constants. The function
compares its arguments to the result returned by
<code>H5get_libversion()</code> and if a mismatch is detected prints
an error message on the standard error stream and aborts.
</dl>
<hr>
<address><a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a></address>
<br>
<!-- Created: Wed Apr 22 11:24:40 EDT 1998 -->
<!-- hhmts start -->
Last modified: Fri Oct 30 10:32:50 EST 1998
<!-- hhmts end -->
</body>
</html>