Package: dpkg
Version: 1.17.9
Severity: normal
Tags: patch
dpkg-gensymbols(1) reads as if applying the dpkg-gensymbols generated
diff to a symbols file was all there was to do for a new upstream
version. Attached patch hopefully fixes that:
>From 7f2679cb82526a14b0c5c3b1418b09c6c2d92762 Mon Sep 17 00:00:00 2001
From: "Bernhard R. Link" <brl...@debian.org>
Date: Sun, 4 May 2014 15:31:54 +0200
Subject: [PATCH] dpkg-gensymbols(1): Fix seriously misleading part about
applying diffs to symbols files
---
man/dpkg-gensymbols.1 | 16 ++++++++++++++--
1 file changed, 14 insertions(+), 2 deletions(-)
diff --git a/man/dpkg-gensymbols.1 b/man/dpkg-gensymbols.1
index 65b042c..bf6c8c0 100644
--- a/man/dpkg-gensymbols.1
+++ b/man/dpkg-gensymbols.1
@@ -61,8 +61,12 @@ option).
The symbols files are really useful only if they reflect the evolution of
the package through several releases. Thus the maintainer has to update
them every time that a new symbol is added so that its associated minimal
-version matches reality. To do this properly the diffs contained in the
-build logs can be used. In most cases, the diff applies directly to the
+version matches reality.
+As as start for this the diffs contained in the build logs can be used,
+but the maintainer has to ensure additionally that the behaviour of that
+symbol was not changed in a way that something using that symbol linked
+against the new version no longer works against the old package.
+In most cases, the diff applies directly to the
debian/\fIpackage\fR.symbols file. That said, further tweaks are usually
needed: it's recommended for example to drop the Debian revision
from the minimal version so that backports with a lower version number
@@ -79,6 +83,14 @@ Note that you can put comments in symbols files: any line
with '#' as the
first character is a comment except if it starts with '#include' (see
section \fBUsing includes\fP). Lines starting with '#MISSING:' are special
comments documenting symbols that have disappeared.
+.P
+Do not forget to check if old symbols' versions needs to be increased.
+There is no way \fBdpkg\-gensymbols\fP can warn you about this.
+Blindly applying the diff or assuming there is nothing to change
+if there is no diff without checking this leads to packages
+with dependencies that claim the package working with older versions
+it cannot work with, thus introducing hard to find bugs with
+(partial) upgrades.
.SS Using #PACKAGE# substitution
.P
In some rare cases, the name of the library varies between architectures.
Bernhard R. Link
--
F8AC 04D5 0B9B 064B 3383 C3DA AFFC 96D1 151D FFDC
--
To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmas...@lists.debian.org
