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