第 8 章 更新软件包

目录

8.1. 新的 Debian 版本
8.2. 检查新上游版本
8.3. 新上游版本
8.4. 更新打包风格
8.5. UTF-8 conversion
8.6. 对更新软件包的几点提示

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

8.1. 新的 Debian 版本

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.

  • 如果要将它记录于新的补丁中,这样做:

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

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

    • 修正软件包代码中的上游 Bug;

    • dquilt refresh to record it to bugname.patch;

    • dquilt header -e to add its description;

  • 如果是更新一个已存在的补丁,这样做:

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

    • 修正旧的 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;

  • 在 Debian changelog 文件的顶部添加一个条目。例如可以使用 dch -i 或用 dch -v version-revision 来指定版本,然后用你喜欢的编辑器插入信息。[78]

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

  • 重复上述操作来修复更多的 Bug,并在需要的时候使用 dch 更新 Debian changelog 文件。

  • Repeat what you did in 第 6.1 节 “完整的(重)构建” and 第 7 章 检查软件包中的错误.

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

  • Upload the package as 第 9 章 上传软件包. 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 第 2.6 节 “软件包名称和版本” for the order of version strings.

8.2. 检查新上游版本

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. 新上游版本

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. [80] Of course, you need to do some obvious chores.

  • 创建一份上游源代码的副本,命名为 foo_newversion.orig.tar.gz

  • 使用 dch -v newversion-1 更新 Debian changelog 文件。

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

如果补丁没有干净地被应用,检查原因(线索在 .rej 文件里)。

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

    • dquilt delete to remove it.

  • 如果你的补丁与上游代码中的变更有冲突:

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

这个过程可以通过使用 uupdate(1) 来更自动化地完成:

$ 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

如果你按照 第 5.22 节 “watch 的叙述设置了 debian/watch 文件,你可以跳过这个 wget 命令,转而在 foo-oldversion 目录中运行 uscan(1),且无需再执行 uupdate 命令。它会 自动 查找新的源代码、下载并运行 uupdate 命令。[81]

重复 第 6.1 节 “完整的(重)构建”第 7 章 检查软件包中的错误第 9 章 上传软件包 中的操作,即可发布此更新的软件包。

8.4. 更新打包风格

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

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

  • 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 第 8.3 节 “新上游版本”, 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=C.UTF-8 w3m -o display_charset=UTF-8 \
            -cols 70 -dump -no-graph -T text/html \
            < foo_in.html > foo_out.txt
    

8.6. 对更新软件包的几点提示

以下是对更新软件包的几点提示。

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

  • 已存在的 Debian 修改需要被重新校验,去除上游已经接受的东西,除非有必要的原因,还要记录尚未被上游接受的部分。

  • 如果对编译系统作出了修改(希望你已经在检查上游变更时了解了这些),那么要在必要时更新 debian/rulesdebian/control 编译依赖关系。

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



[78] 要获得需要的日期格式,使用 LANG=C date -R

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

[80] 如果软件包 foo 是使用旧的 1.0 格式的,可以在新解压的源代码目录里运行 zcat /path/to/foo_oldversion.diff.gz|patch -p1 来完成。

[81] 如果 uscan 命令下载并更新了源代码,但没有运行 uupdate 命令,你应该修正 debian/watch 文件,使 URL 末尾后带有 debian uupdate

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

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