[SCM] hdf5 branch, master, updated. upstream/1.8.7-189-gce5459b

[Gilles Filippini]

The following commit has been merged in the master branch:
commit ce5459bf2419529714df0fa1610650bf7119fcfd
Author: Gilles Filippini <pini at debian.org>
Date:   Thu Dec 5 23:28:59 2013 +0100

    debian/README.source: update soname / symbols info

diff --git a/debian/README.source b/debian/README.source
index f9c6f57..fd0b20e 100644
--- a/debian/README.source
+++ b/debian/README.source
@@ -11,15 +11,45 @@ the HDF Group svn repository:
 
 svn export https://svn.hdfgroup.uiuc.edu/hdf5doc/branches/hdf5_1_8_4/html
 
-and a tarball is created by cleaning Makfiles and other stuff. The resulting
-archive is provided as a uuencoded archive.
+[Not true anymore]
+> and a tarball is created by cleaning Makefiles and other stuff. The resulting
+> archive is provided as a uuencoded archive.
 
-About versioning style. In very recent times (since 1.8 series) HDF Group
-introduced a libtool SONAME versioning in the library with major/minor releases.
-Unfortunately, past experieces showed that API retention has been sometimes
-violated in the past, so current packages use a defensive approach by considering
-each release as not back-compatible. This is also motivated by the presence of
-of C++ and Fortran bindings as well as multiple MPI editions, which could imply 
-ABI breakages even for minor releases. Be defensive is more safe, definitively
+About symbols files
+-------------------
+To update the symbols files on new upstream releases:
+1- Build the package for the new release with symbols files untouched
+2- Patch the symbols files from the dpkg-gensymbols output in the build log
+   $ patch -p0 <path_to_build_log
+3- Use the debian/sort-symbols script on the symbol files to unmangle and
+   and sort C++ symbols
+4- Rebuild the package and check that no diff are reported by dpkg-gensymbols
+
+About shared libraries versioning and SONAME
+--------------------------------------------
+Worth reading to get the picture about libtool versioning:
+<http://bzed.de/scratchpad/soname-libtool.txt>
+
+[Old note - for the record]
+> About versioning style. In very recent times (since 1.8 series) HDF Group
+> introduced a libtool SONAME versioning in the library with major/minor releases.
+> Unfortunately, past experieces showed that API retention has been sometimes
+> violated in the past, so current packages use a defensive approach by considering
+> each release as not back-compatible. This is also motivated by the presence of
+> of C++ and Fortran bindings as well as multiple MPI editions, which could imply 
+> ABI breakages even for minor releases. Be defensive is more safe, definitively
+
+Looking at the 1.8.x releases, it seems that upstream doesn't apply the
+libtool versioning strategy. Instead they use it the major.medium.minor way
+where:
+* medium=0
+* minor++ on release
+* major++, minor=0 on API breaks
+
+Considering applying this piece of advice from Julien Cristau:
+> J'aurais tendance à suggérer d'utiliser le switch -version-number de
+> libtool plutôt que -version-info.  Ça prend directement comme argument
+> major:minor:micro, donc on se perd pas dans des calculs à la con.
 
  -- Francesco Paolo Lovergine <frankie at debian.org> Mon Jan 25 06:00:00 CET 2010
+ -- Gilles Filippini <pini at debian.org>  Thu, 05 Dec 2013 23:04:45 +0100

-- 
Hierarchical Data Format 5 (HDF5)