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 -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of "unsubscribe". Trouble? Contact listmas...@lists.debian.org
