Debian Bug report logs - #746973
dpkg-gensymbols(1) is misleading to omit important part of symbols file maintainance

Display info messages

Message #5 received at submit@bugs.debian.org (full text, mbox, reply):

From: "Bernhard R. Link" <brlink@debian.org>

To: Debian Bug Tracking System <submit@bugs.debian.org>

Subject: dpkg-gensymbols(1) is misleading to omit important part of symbols file maintainance

Date: Sun, 4 May 2014 15:39:27 +0200

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" <brlink@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

Message #10 received at 746973@bugs.debian.org (full text, mbox, reply):

From: Guillem Jover <guillem@debian.org>

To: "Bernhard R. Link" <brlink@debian.org>, 746973@bugs.debian.org

Subject: Re: Bug#746973: dpkg-gensymbols(1) is misleading to omit important part of symbols file maintainance

Date: Sun, 4 May 2014 16:47:06 +0200

Hi!

On Sun, 2014-05-04 at 15:39:27 +0200, Bernhard R. Link wrote:
> 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:

Thanks! I think there's some wording issues though, here's how I'll
be rewritting for now, if it seems good (although I'm not a native
speaker, so…), before queueing it for 1.17.10:

> @@ -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.

The diffs contained in the build logs can be used as a starting point,
but the maintainer, additionally, has to make sure that the behaviour
of those symbols has not changed in a way that would make anything
using those symbols and linking against the new version, stop working
with the old version.

> +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.

Do not forget to check if old symbol versions need to be increased.
There is no way \fBdpkg\-gensymbols\fP can warn about this, and blindly
applying the diff or assuming there is nothing to change if there is
no diff, without checking for such changes, can lead to packages with
loose dependencies that claim they can work with older packages they
cannot work with, thus introducing hard to find bugs with (partial)
upgrades.


Thanks,
Guillem

Message #15 received at 746973-submitter@bugs.debian.org (full text, mbox, reply):

From: Guillem Jover <guillem@debian.org>

To: 746973-submitter@bugs.debian.org

Subject: Bug#746973 marked as pending

Date: Sat, 17 May 2014 12:09:16 +0000

tag 746973 pending
thanks

Hello,

Bug #746973 reported by you has been fixed in the Git repository. You can
see the changelog below, and you can check the diff of the fix at:

    http://git.debian.org/?p=dpkg/dpkg.git;a=commitdiff;h=789d242

---
commit 789d2428488f481cef86661d445175ea8316be4f
Author: Guillem Jover <guillem@debian.org>
Date:   Wed May 14 04:40:35 2014 +0200

    dpkg-gensymbols(1): Improve symbols file maintenance documentation
    
    Add notes about checking for backwards compatibility.
    
    Closes: #746973
    
    Based-on-patch-by: "Bernhard R. Link" <brlink@debian.org>

diff --git a/debian/changelog b/debian/changelog
index 4d10ca4..5c40f2a 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -29,6 +29,9 @@ dpkg (1.17.10) UNRELEASED; urgency=low
       deb-src-control(5) to make it easier to search for them.
     - Change control.tar.gz reference to simply control.tar in deb(5).
     - Document in dpkg-deb(1) -Z option that bzip2 and lzma are deprecated.
+    - Add notes in dpkg-gensymbols(1) about symbol backward-compatibility.
+      Based on a patch by Bernhard R. Link <brlink@debian.org>.
+      Closes: #746973
 
   [ Updated manpages translations ]
   * German (Helge Kreutzmann).

Message #20 received at 746973-close@bugs.debian.org (full text, mbox, reply):

From: Guillem Jover <guillem@debian.org>

To: 746973-close@bugs.debian.org

Subject: Bug#746973: fixed in dpkg 1.17.10

Date: Thu, 05 Jun 2014 19:48:41 +0000

Source: dpkg
Source-Version: 1.17.10

We believe that the bug you reported is fixed in the latest version of
dpkg, which is due to be installed in the Debian FTP archive.

A summary of the changes between this version and the previous one is
attached.

Thank you for reporting the bug, which will now be closed.  If you
have further comments please address them to 746973@bugs.debian.org,
and the maintainer will reopen the bug report if appropriate.

Debian distribution maintenance software
pp.
Guillem Jover <guillem@debian.org> (supplier of updated dpkg package)

(This message was generated automatically at their request; if you
believe that there is a problem with it please contact the archive
administrators by mailing ftpmaster@ftp-master.debian.org)


-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

Format: 1.8
Date: Thu, 05 Jun 2014 20:18:04 +0200
Source: dpkg
Binary: libdpkg-dev dpkg dpkg-dev libdpkg-perl dselect
Architecture: source amd64 all
Version: 1.17.10
Distribution: unstable
Urgency: medium
Maintainer: Dpkg Developers <debian-dpkg@lists.debian.org>
Changed-By: Guillem Jover <guillem@debian.org>
Description: 
 dpkg       - Debian package management system
 dpkg-dev   - Debian package development tools
 dselect    - Debian package management front-end
 libdpkg-dev - Debian package management static library
 libdpkg-perl - Dpkg perl modules
Closes: 584233 731530 734452 746122 746498 746973 747148 747370 748012 748544 749044 749183 750105
Changes: 
 dpkg (1.17.10) unstable; urgency=medium
 .
   [ Guillem Jover ]
   * Use libtool to build the static libraries, which makes it possible to
     embed libcompat inside libdpkg, as required by some external programs
     linking against the latter. Closes: #746122
   * Fix word wrapping logic in dselect. Regression introduced in dpkg 1.17.3.
   * Fix possible out of bounds buffer read access in the error output on
     bogus ar member sizes.
   * Fix memory leaks in buffer_copy() on error conditions.
   * Test suite:
     - Improve C code coverage.
     - Add template test cases for most perl modules.
     - Add test cases for Dpkg::Deps OR relationships.
     - Add minimal test case for Dpkg::Source::Quilt.
     - Add test cases for Dpkg::Source::Patch CVE-2014-0471 and CVE-2014-3127.
     - Add test case for patch disabling hunks; not security sensitive.
   * Fix non-security sensitive TOCTOU race in triggers database loading.
   * Fix non-security sensitive TOCTOU race in update-alternative alternative
     database loading.
   * Fix non-security sensitive TOCTOU race in update-alternative rename code.
   * Add a workaround to start-stop-daemon for bogus OpenVZ Linux kernels that
     prepend, instead of appending, the " (deleted)" marker in /proc/PID/exe.
     Closes: #731530
   * Move dpkg-architecture -L argument to the Commands --help output section.
   * Make dpkg-maintscript-helper print only once that we are moving a
     conffile, and not on every interim state transition. Closes: #747370
   * Do not use global match variables in perl code.
   * Man pages:
     - Attempt to clarify and improve wording of some strange or confused
       constructs. Reported by Helge Kreutzmann.
     - Expand Vcs-* field names into each supported field name in
       deb-src-control(5) to make it easier to search for them.
     - Change control.tar.gz reference to simply control.tar in deb(5).
     - Document in dpkg-deb(1) -Z option that bzip2 and lzma are deprecated.
     - Add notes in dpkg-gensymbols(1) about symbol backward-compatibility.
       Based on a patch by Bernhard R. Link <brlink@debian.org>.
       Closes: #746973
     - Document that dpkg-buildpackage(1) -j argument is optional.
     - Add current and deprecated media types to deb(5).
     - Document in dpkg(1) that --audit now does more than just searching for
       partially installed packages.
   * Add support for automatic parallel job selection in dpkg-buildpackage,
     matching currently active processors, when using -jauto. Closes: #748012
   * Perl modules:
     - Bump $VERSION for Dpkg::Patch, missed in 1.16.1.
     - Bump $VERSION for Dpkg::Deps, missed in 1.17.0.
     - Update and fix CHANGES POD sections for public modules.
     - Add missing Dpkg::Deps::Multiple profile_is_concerned() and
       reduce_profiles() methods, inherited by Dpkg::Deps::Union,
       Dpkg::Deps::AND and Dpkg::Deps::OR.
   * Do not mangle quilt series files with a missing newline on the last line.
     Closes: #584233
   * Quiesce tar warnings in cron job by redirecting stderr to /dev/null, as
     it seems --warning=none does not work correctly. Closes: #748544
   * Do not emit a trailing space from Dpkg::Control::Hash on a field's empty
     first line. Bump dpkg-dev Breaks on devscripts to 2.14.4, as previous
     versions expect a trailing space from dpkg-parsechangelog output.
     Based on a patch by Johannes Schauer <j.schauer@email.de>. Closes: #749044
   * Do not assume that sensible-editor is present on «dpkg-source --commit»,
     as that command is very Debian specific. Fallback to try VISUAL, EDITOR,
     or vi, if the previous commands are either unset or not found.
   * Use badusage() instead of ohshit() on dpkg --ignore-depends argument
     parsing errors.
   * Add per package dpkg --audit support.
   * Add support for DragonFlyBSD to ostable and triplettable.
     Thanks to Hleb Valoshka <375gnu@gmail.com>.
   * Add support for DragonFlyBSD to start-stop-daemon. Closes: #734452
     Based on a patch by Hleb Valoshka <375gnu@gmail.com>.
   * Correctly parse patch headers in Dpkg::Source::Patch, to avoid directory
     traversal attempts from hostile source packages when unpacking them.
     Reported by Javier Serrano Polo <javier@jasp.net> as an unspecified
     directory traversal; meanwhile also independently found by me both
     #749183 and what was supposed to be #746498, which was later on published
     and ended up being just a subset of the other non-reported issue.
     Fixes CVE-2014-3864 and CVE-2014-3865. Closes: #746498, #749183
 .
   [ Updated programs translations ]
   * Catalan (Guillem Jover).
   * Italian (Milo Casagrande). Closes: #750105
 .
   [ Updated scripts translations ]
   * German (Helge Kreutzmann).
 .
   [ Updated manpages translations ]
   * German (Helge Kreutzmann).
 .
   [ Raphaël Hertzog ]
   * Let dpkg-source unpack additional tarballs in a deterministic order.
     Thanks to Samuel Bronson for the report. Closes: #747148
Checksums-Sha1: 
 c91e1e1bb0dc5918f20e3874c4b371425dac0da3 2055 dpkg_1.17.10.dsc
 2d88ef04db662d046fadb005bb31667fc0ba64de 4198340 dpkg_1.17.10.tar.xz
 be325d2d7fac12f031e537b5ed269724542f118c 799530 libdpkg-dev_1.17.10_amd64.deb
 ab90f4afdca78f0a5b8cf359b6c1c31c8c3f9e66 2704088 dpkg_1.17.10_amd64.deb
 6e9d00f6e0e8155085c619090292a548373842c5 1059422 dselect_1.17.10_amd64.deb
 8c56a5720faf36231f2ce88c271d34941bb4d61b 1425374 dpkg-dev_1.17.10_all.deb
 6bbd6bddfe2a6af99cfbf547e5de9abbb48d7a81 974696 libdpkg-perl_1.17.10_all.deb
Checksums-Sha256: 
 8552763122f36a4ede1e040dee28a84202de9f4b65dbcc90e2c068101d2a599d 2055 dpkg_1.17.10.dsc
 a3a6d4da2b99484c04b2aa8af83d59d87a988baea627d276308467b22310b4d9 4198340 dpkg_1.17.10.tar.xz
 a6b8ed0b95af7748ee3daf9e297c94bb0ab166d7908bbc46e2f5ef5ab93c08b1 799530 libdpkg-dev_1.17.10_amd64.deb
 81a2e6111e825e8a01caa8bf2c8876d806fe9e7297deea0eb61e5a9d93c9a82c 2704088 dpkg_1.17.10_amd64.deb
 1a8a3924786f18c9e0432b8cb34c8c99576dd96221fab9cda2a0f3b5b7606d51 1059422 dselect_1.17.10_amd64.deb
 ba58996d596f73a312b9d92bf01f40f2eeac1ba6db4011875bfbd685371c9619 1425374 dpkg-dev_1.17.10_all.deb
 702028918cfda7e1eaf7391717818b2e6dd05b00b02e4091ea084791e8308234 974696 libdpkg-perl_1.17.10_all.deb
Files: 
 7c8852829f4caa99b6c3a232915ac28c 799530 libdevel optional libdpkg-dev_1.17.10_amd64.deb
 90ba5aa300a72a9a54eeda5990b2641f 2704088 admin required dpkg_1.17.10_amd64.deb
 b6f581a13931bfedde3719dc4340b476 1059422 admin optional dselect_1.17.10_amd64.deb
 405cccbb6024ecb98fa6fc8939365cbc 1425374 utils optional dpkg-dev_1.17.10_all.deb
 be5fa2aa735a59ec34d1e4c889c6b7d4 974696 perl optional libdpkg-perl_1.17.10_all.deb
 274a6b2892d179ed04ad916dd2103676 2055 admin required dpkg_1.17.10.dsc
 545f3cbac8b5f0b3d888574f3f79936c 4198340 admin required dpkg_1.17.10.tar.xz

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.22 (GNU/Linux)

iQIcBAEBCAAGBQJTkMS1AAoJELlyvz6krlejNxcP+wT/0vQECEQh1CI3DIS9aPYE
FfvmpoHioGn8dE8Su318SeZy+IADIis9IeE6GytqwMGIIekh6tC4ES574GRuLiRc
Edy4IrAlLnrGfM5VbAh5f1F9vmgZkBy2Z8R/oRjnQthgy5SUbGe1Bx9jqbh2sR4k
94EsdCuAxTiDI9+O15prM2u3Vxe7TD4Z7n9kjD3Tj35THVp6okpj1qGbTQ9bQJ04
nIcaWtZf6NXxyTNvXJ9Ac8Cdv47q1/CB4yXNQf47v0U6Rjorvh3EHkWyEtVpP1Ps
JVprxVwuxb9ayYn5j2MeBcMWS3igyowsh9a23+lZCwz0SALChZMHeYV74TB1/b8p
Gc53g6jSjI6bKK5xy5hst7tcG/ALmY0HE+jpkgVK/EJPwGKYq1julwgjd6kmrHA+
MBGs3p5ZTbR2PmzLYAmyzD2Ctabz7dFHZpMJ0c3pPsrGLUYD89gSZqp2k4zmrPIp
EEkhJNCsUFJbnG0ZpEw5aYCCHgPcKWazvsGh/DgYYytrWatJkmzgZi4I8KW+jEYG
85volBskw5V6aqJWJ9Sum/W2A11iR3El46YKqfqqSI83D2ucLWE5eXaMF3o5x+LP
AJ/XshrbiouHSu4GKiH/N7WGbD9OSYpnU/fdNbtiw+GNUC5KfsztDFWUWmiX4JP1
XzNrK95rGu/atNhtRghC
=d8BF
-----END PGP SIGNATURE-----

Send a report that this bug log contains spam.