Kapitel 9. Updating the package
Zurück   Weiter

Kapitel 9. Updating the package

Inhaltsverzeichnis

9.1. New Debian revision
9.2. Inspection of the new upstream release
9.3. New upstream release
9.4. Updating the packaging style
9.5. UTF-8 conversion
9.6. Reminders for updating packages

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

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

  • If this is to be recorded as a new patch, do the following.

    • dquilt new bugname.patch to set the patch name;

    • dquilt add buggy-file to declare the file to be modified;

    • Correct the problem in the package source for the upstream bug;

    • dquilt refresh to record it to bugname.patch;

    • dquilt header -e to add its description;

  • If this is to update an existing patch, do the following.

    • dquilt pop foo.patch to recall the existing foo.patch;

    • Correct the problem in the old foo.patch;

    • dquilt refresh to update foo.patch;

    • dquilt header -e to update its description;

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

  • Add a new revision at the top of the Debian changelog file, for example with dch -i, or explicitly with dch -v version-revision and then insert the comments using your preferred editor. [83]

  • Include a short description of the bug and the solution in the changelog entry, followed by Closes: #654321. That way, the bug report will be automagically closed by the archive maintenance software the moment your package gets accepted into the Debian archive.

  • Repeat what you did in the above to fix more bugs while updating the Debian changelog file with dch as needed.

  • Repeat what you did in Abschnitt 6.1, „Kompletter (Neu-)Bau“ and Kapitel 7, Checking the package for errors.

  • Once you are satisfied, you should change the distribution value in changelog from UNRELEASED to the target distribution value unstable (or even experimental).[84]

  • Upload the package as Kapitel 8, Uploading the package. The difference is that this time, the original source archive won't be included, as it hasn't been changed and it already exists in the Debian archive.

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 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 Abschnitt 2.6, „Name und Version des Pakets“ for the order of version strings.

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

9.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. [85] 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 Abschnitt 5.22, „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. [86]

You can release this updated source by repeating what you did in Abschnitt 6.1, „Kompletter (Neu-)Bau“, Kapitel 7, Checking the package for errors, and Kapitel 8, Uploading the package.

9.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. [87]

  • 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. [88]

  • If it was packaged using another patch system such as dpatch, dbs, or cdbs with -p0, -p1, or -p2, convert it to the quilt command 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 (native) source format.

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

You need to do the other tasks described in Abschnitt 9.3, „New upstream release“, too.

9.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=C.UTF-8 w3m -o display_charset=UTF-8 \
        -cols 70 -dump -no-graph -T text/html \
        < foo_in.html > foo_out.txt

9.6. Reminders for updating packages

Here are few reminders for updating packages.

  • Preserve old changelog entries (sounds obvious, but there have been cases of people typing dch when they should have typed dch -i.)

  • Existing Debian changes need to be reevaluated; throw away stuff that upstream has incorporated (in one form or another) and remember to keep stuff that hasn't been incorporated by upstream, unless there is a compelling reason not to.

  • If any changes were made to the build system (hopefully you'd know from inspecting upstream changes) then update the debian/rules and debian/control build dependencies if necessary.

  • Check the Debian Bug Tracking System (BTS) to see if someone has provided patches to bugs that are currently open.

  • Check the contents of the .changes file to make sure you are uploading to the correct distribution, the proper bug closures are listed in the Closes field, the Maintainer and Changed-By fields match, the file is GPG-signed, etc.


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

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

[85] 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.

[86] 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.

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

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

Zurück   Weiter
Kapitel 8. Uploading the package Zum Anfang Anhang A. Advanced packaging