Chapter 8. Updating the package
Prev     Next

Chapter 8. Updating the package

Table of Contents

8.1. New Debian revision
8.2. Inspection of the new upstream release
8.3. New upstream release
8.4. Updating the packaging style
8.5. UTF-8 conversion
8.6. Reminders for updating packages

The rewrite of this tutorial document with updated contents and more practical examples is available as Guide for Debian Maintainers. Please use this new tutorial as the primary tutorial document.

After you release a package, you will soon need to update it.

8.1. New Debian revision

Let's say that a bug report was filed against your package as #654321, and it describes a problem that you can solve. Here's what you need to do to create a new Debian revision of the package:

One tricky case can occur when you make a local package, to experiment with the packaging before uploading the normal version to the official archive, e.g., 1.0.1-1. For smoother upgrades, it is a good idea to create a changelog entry with a version string such as 1.0.1-1~rc1. You may unclutter changelog by consolidating such local change entries into a single entry for the official package. See Section 2.6, “Package name and version” for the order of version strings.

8.2. Inspection of the new upstream release

When preparing packages of a new upstream release for the Debian archive, you must check the new upstream release first.

Start by reading the upstream changelog, NEWS, and whatever other documentation they may have released with the new version.

You can then inspect changes between the old and new upstream sources as follows, watching out for anything suspicious: 

$ diff -urN foo-oldversion foo-newversion

Changes to some auto-generated files by Autotools such as missing, aclocal.m4, config.guess, config.h.in, config.sub, configure, depcomp, install-sh, ltmain.sh, and Makefile.in may be ignored. You may delete them before running diff on the source for inspection.

8.3. New upstream release

If a package foo is properly packaged in the newer 3.0 (native) or 3.0 (quilt) formats, packaging a new upstream version is essentially moving the old debian directory to the new source. This can be done by running tar xvzf /path/to/foo_oldversion.debian.tar.gz in the new extracted source. [78] Of course, you need to do some obvious chores:

  • Create a copy of the upstream source as the foo_newversion.orig.tar.gz file.

  • Update the Debian changelog file with dch -v newversion-1.

    • Add an entry with New upstream release.

    • Describe concisely the changes in the new upstream release that fix reported bugs and close those bugs by adding Closes: #bug_number.

    • Describe concisely the changes to the new upstream release by the maintainer that fix reported bugs and close those bugs by adding Closes: #bug_number.

  • while dquilt push; do dquilt refresh; done to apply all patches while removing fuzz.

If the patch/merge did not apply cleanly, inspect the situation (clues are left in .rej files).

  • If a patch you applied to the source was integrated into the upstream source,

    • dquilt delete to remove it.

  • If a patch you applied to the source conflicted with new changes in the upstream source,

    • dquilt push -f to apply old patches while forcing rejects as baz.rej.

    • Edit the baz file manually to bring about the intended effect of baz.rej.

    • dquilt refresh to update the patch.

  • Continue as usual with while dquilt push; do dquilt refresh; done.

This process can be automated using the uupdate(1) command as follows: 

$ apt-get source foo
...
dpkg-source: info: extracting foo in foo-oldversion
dpkg-source: info: unpacking foo_oldversion.orig.tar.gz
dpkg-source: info: applying foo_oldversion-1.debian.tar.gz
$ ls -F
foo-oldversion/
foo_oldversion-1.debian.tar.gz
foo_oldversion-1.dsc
foo_oldversion.orig.tar.gz
$ wget http://example.org/foo/foo-newversion.tar.gz
$ cd foo-oldversion
$ uupdate -v newversion ../foo-newversion.tar.gz
$ cd ../foo-newversion
$ while dquilt push; do dquilt refresh; done
$ dch
... document changes made

If you set up a debian/watch file as described in Section 5.21, “watch”, you can skip the wget command. You simply run uscan(1) in the foo-oldversion directory instead of the uupdate command. This will automagically look for the updated source, download it, and run the uupdate command. [79]

You can release this updated source by repeating what you did in Section 6.1, “Complete (re)build”, Chapter 7, Checking the package for errors, and Chapter 9, Uploading the package.

8.4. Updating the packaging style

Updating the package style is not a required activity for the update of a package. However, doing so lets you use the full capabilities of the modern debhelper system and the 3.0 source format. [80]

  • If you need to recreate deleted template files for any reason, you can run dh_make again in the same Debian package source tree with the --addmissing option. Then edit them appropriately.

  • If the package has not been updated to use the debhelper v7+ dh syntax for the debian/rules file, update it to use dh. Update the debian/control file accordingly.

  • If you want to update the rules file created with the Makefile inclusion mechanism of the Common Debian Build System (cdbs) to the dh syntax, see the following to understand its DEB_* configuration variables.

  • If you have a 1.0 source package without the foo.diff.gz file, you can update it to the newer 3.0 (native) source format by creating debian/source/format with 3.0 (native). The rest of the debian/* files can just be copied.

  • If you have a 1.0 source package with the foo.diff.gz file, you can update it to the newer 3.0 (quilt) source format by creating debian/source/format with 3.0 (quilt). The rest of the debian/* files can just be copied. Import the big.diff file generated by the command filterdiff -z -x '*/debian/*' foo.diff.gz > big.diff to your quilt system, if needed. [81]

  • If it was packaged using another patch system such as dpatch, dbs, or cdbs with -p0, -p1, or -p2, convert it to quilt using deb3 at http://bugs.debian.org/581186.

  • If it was packaged with the dh command with the --with quilt option or with the dh_quilt_patch and dh_quilt_unpatch commands, remove these and make it use the newer 3.0 (quilt) source format.

You should check DEP - Debian Enhancement Proposals and adopt ACCEPTED proposals.

You need to do the other tasks described in Section 8.3, “New upstream release”, too.

8.5. UTF-8 conversion

If upstream documents are encoded in old encoding schemes, converting them to UTF-8 is a good idea.

  • Use iconv(1) to convert encodings of plain text files. 

    iconv -f latin1 -t utf8 foo_in.txt > foo_out.txt

  • Use w3m(1) to convert from HTML files to UTF-8 plain text files. When you do this, make sure to execute it under UTF-8 locale. 

    LC_ALL=en_US.UTF-8 w3m -o display_charset=UTF-8 \
        -cols 70 -dump -no-graph -T text/html \
        < foo_in.html > foo_out.txt

8.6. Reminders for updating packages

Here are a few reminders for updating packages:


[76] To get the date in the required format, use LANG=C date -R.

[77] If you use the dch -r command to make this last change, please make sure to save the changelog file explicitly by the editor.

[78] If a package foo is packaged in the old 1.0 format, this can be done by running zcat /path/to/foo_oldversion.diff.gz|patch -p1 in the new extracted source, instead.

[79] If the uscan command downloads the updated source but it does not run the uupdate command, you should correct the debian/watch file to have debian uupdate at the end of the URL.

[80] If your sponsor or other maintainers object to updating the existing packaging style, don't bother arguing. There are more important things to do.

[81] You can split big.diff into many small incremental patches using the splitdiff command.

Prev     Next
Chapter 7. Checking the package for errors  Home  Chapter 9. Uploading the package