Shishi/GSS no-symbols-control-file lintian warning

[Simon Josefsson]

Hi Russ.  I am building new Shishi/GSS packages (don't worry, I won't
upload to unstable until after lenny has been released) and ran into:

I: libgss0: no-symbols-control-file usr/lib/libgss.so.0.0.24
N:
N:   Although the package includes a shared library, the package does not
N:   have a symbols control file.
N:   
N:   dpkg can use symbols files in order to generate more accurate library
N:   dependencies for applications, based on the symbols from the library
N:   that are actually used by the application.
N:   
N:   Refer to the dpkg-gensymbols(1) manual page for details.
N:   
N:   Severity: wishlist; Certainty: certain
N:

I tried to read up about this...  I am able to generate a symbols list
using 'dpkg-gensymbols -plibgss0 -Ofoo':

libgss.so.0 libgss0 #MINVER#
 address@hidden 0.0.24-1
 address@hidden 0.0.24-1
 address@hidden 0.0.24-1
 address@hidden 0.0.24-1
 address@hidden 0.0.24-1
...

However, I haven't found a simple to understand explanation of best
practices on how to modify this file.  deb-symbols man page doesn't help
me, nor does <http://wiki.debian.org/Projects/ImprovedDpkgShlibdeps>.

I tried to just put the output above into libgss0.dev, however that
resulted in lintian warnings:

E: libgss0: symbols-file-contains-current-version-with-debian-revision on 
symbol address@hidden and 90 others
N:
N:   Debian revisions should be stripped from versions in symbols files.
N:   Not doing so leads to dependencies unsatisfiable by backports
N:   (1.0-1~bpo << 1.0-1 while 1.0-1~bpo >= 1.0). If the debian revision
N:   can't be stripped because the symbol really appeared between two
N:   specific Debian revisions, you should postfix the version with a
N:   single "~" (example: 1.0-3~ if the symbol appeared in 1.0-3).
N:   
N:   This problem normally means that the symbols were added automatically
N:   by dpkg-gensymbols. dpkg-gensymbols uses the full version number for
N:   the dependency associated to any new symbol that it detects. The
N:   maintainer must update the debian/<package>.symbols file by adding the
N:   new symbols with the corresponding upstream version.
N:   
N:   Severity: important; Certainty: certain
N:
W: libgss0: symbols-file-contains-debian-revision on symbol address@hidden and 
90 others
N:
N:   Debian revisions should be stripped from versions in symbols files.
N:   Not doing so leads to dependencies unsatisfiable by backports
N:   (1.0-1~bpo << 1.0-1 while 1.0-1~bpo >= 1.0). If the debian revision
N:   can't be stripped because the symbol really appeared between two
N:   specific Debian revisions, you should postfix the version with a
N:   single "~" (example: 1.0-3~ if the symbol appeared in 1.0-3).
N:   
N:   Severity: normal; Certainty: certain
N:

IMHO, dpkg-gensymbols could have avoided adding the -1 itself...
Anyway, I removed the '-1' part in the .symbols file, rebuild the
packages, and now lintian is quiet.

However questions remains:

* Did I do the right thing above?  The symbols file is part of
  debian-gss CVS if you want to take a look.

* Do I have to modify the file considering that debian unstable contains
  0.0.23 with the same ABI?

* What should I do on next release with no ABI changes?  Keep the
  version number as is in the .symbols file?

* What should I do on next release with ABI changes?  Add the new ABI to
  the .symbols file with the newer version number?

* Generally, should I bother with a *.symbols file at all?  I get a
  feeling from the wiki page that people haven't really decided that
  this is the way to go, and I haven't found many debian packages that
  use a *.symbols file either.

/Simon