章 8. 更新套件

# 章 8. 更新套件

本教程文件已被重寫為另外的 Debian 維護者指導 文件，其中包含了更新的內容與更多實際例子。請使用新的教程作為主要的教程文件。

一旦你發佈了一個軟件包，在之後的某個時間裏就需要對它進行更新。

## 8.1. 新的 Debian 版本

假設你收到一個針對你的軟件包報告的 Bug ，其編號爲 `#654321`，它描述了一個你可以解決的問題。要創建軟件包的一個新 Debian 修訂版本，你需要：

- 如果要將它記錄於新的補丁中，這樣做：

  - `dquilt new `bugname.patch`` 設置補丁名稱；

  - `dquilt add `buggy-file`` 聲明文件將被更改；

  - 修正套件程式碼中的上游 Bug；

  - `dquilt refresh` 將修改記錄到 ``bugname.patch``；

  - `dquilt header -e` 添加對它的描述；

- 如果是更新一個已存在的補丁，這樣做：

  - `dquilt pop `foo.patch`` 重現已存在的 ``foo.patch``；

  - 修正舊的 ``foo.patch`` 中的問題；

  - `dquilt refresh` 更新 ``foo.patch``；

  - `dquilt header -e` 更新對它的描述；

  - `while dquilt push; do dquilt refresh; done` 應用所有補丁以確保它們 邊界清晰；

- 在 Debian `changelog` 檔案的頂部添加一個條目。例如可以使用 `dch -i` 或用 `dch -v `version`-`revision`` 來指定版本，然後用你喜歡的編輯器插入訊息。[76]

- 在 changlog 條目中簡要描述 Bug 和相應的解決辦法，並在後面添加 `Closes: #654321`。這樣 Bug 報告會在你的軟件包被 Debian 倉庫接受的同時被倉庫管理軟件 自動關閉。

- 重複上述操作來修復更多的 Bug，並在需要的時候使用 `dch` 更新 Debian `changelog` 檔案。

- 重複你在 節 6.1, “完整的(重)構建” 和 章 7, 檢査套件中的錯誤 中所做的事情。

- 一旦你滿意了，那就將 `changelog` 中的發行版值由 `UNRELEASED` 修改成 目標發行版值 `unstable` (或者是 `experimental`)。[77]

- 按照 章 9, 上傳套件 來上傳軟體包。惟一的區別是這次不需要再包含原始程式碼檔案，因為它們沒有變化且已經存在於 Debian 倉庫中。

有一種棘手的情況，當你在上傳正常版本到官方倉庫中之前，你製作了一個本地包以進行打包實驗，例如, ``1.0.1`-`1``。 為了平滑升級，建立一個 `changelog` 條目，其中包含類似``1.0.1`-`1~rc1`` 這樣的版本字串不失為一劑良方。 你可以透過合併這樣的本地修改條目到官方包的單個條目中來整理 `changelog`。 參見 節 2.6, “套件名稱和版本” 來了解版本字串的排序。

## 8.2. 檢査新上游版本

在為 Debian 倉庫準備新上游版本的軟體包前，你必須首先對新的上游釋出版本進行檢查。

檢查工作應從閱讀上游 `changelog`、`NEWS` 以及所有隨新版本一同發佈的文檔。

然後應按照以下步驟檢查新舊版本之間源碼的差別，小心任何可疑的內容：

    $ diff -urN foo-oldversion foo-newversion

對於 Autotools 自動生成的文件發生的改動，例如 `missing`、`aclocal.m4`、`config.guess`、`config.h.in`、`config.sub`、`configure`、`depcomp`、`install-sh`、`ltmain.sh` 和 `Makefile.in` 是可以忽略的。你可以在運行 diff 進行代碼檢查前刪除它們。

## 8.3. 新上游版本

如果軟件包 ``foo`` 是使用新的 `3.0 (native)` 或 `3.0 (quilt)` 格式打包的，製作新的上游版本時需要先把舊的 `debian` 目錄移至新的源代碼內。這可以通過在新解壓的源代碼目錄裏運行 `tar xvzf /`path`/`to`/`foo`_`oldversion`.debian.tar.gz` 完成。[78]當然，你需要做幾個很顯然的雜事：

- 創建一份上游原始碼的副本，命名爲 `foo_`newversion`.orig.tar.gz`

- 使用 `dch -v `newversion`-`1`` 更新 Debian `changelog` 檔案。

  - 添加一個條目，內容爲 `New upstream release`。

  - 簡明地介紹 在新上游版本中 上游修復和關閉的 Bug (添加 `Closes: #`bug_number``) 。

  - 簡明地介紹維護者對 本個新上游版本 做出的修改，修復和關閉的 Bug (添加 `Closes: #`bug_number``)。

- 運行 `while dquilt push; do dquilt refresh; done` 以應用全部補丁並使它們 邊界清晰。

如果補丁沒有乾淨地被應用，檢査原因(線索在 `.rej` 檔案裏)。

- 如果你的補丁已經被上游接受，

  - 使用 `dquilt delete` 刪除它。

- 如果你的補丁與上遊程式碼中的變更有衝突：

  - 使用 `dquilt push -f` 應用舊補丁，未應用的部分會被保存爲 ``baz`.rej`。

  - 手工編輯 ``baz`` 文件來在新的代碼中實現 ``baz`.rej` 中應有的效果。

  - 使用 `dquilt refresh` 更新補丁。

- 正常繼續，執行 `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.21, “`watch`” 的敘述設置了 `debian/watch` 檔案，你可以跳過這個 wget 命令，轉而在 ``foo`-`oldversion`` 目錄中運行 uscan(1)，且無需再執行 uupdate 命令。它會 自動 査找新的原始碼、下載並運行 uupdate 命令。[79]

重複 節 6.1, “完整的(重)構建” 、章 7, 檢査套件中的錯誤 和 章 9, 上傳套件 中的操作，即可發佈此更新的套件。

## 8.4. 更新打包風格

更新打包風格不是更新軟件包的必須步驟，但是這樣可以使你的軟件包得到對現代的 `debhelper` 系統和 `3.0` 源代碼包格式完整的兼容性。[80]

- 如果你需要重新添加已刪除的模板文件，可以在同一個 debian 軟件包源代碼樹中運行 dh_make，並添加 `--addmissing` 選項。然後對模板進行相應的編輯。

- 如果軟件包的 `debian/rules` 文件沒有更新爲使用 `debhelper` v7+ 的 dh 語法，則更新它使用 dh。在需要的時候更新 `debian/control` 文件。

- 如果你希望將使用 `cdbs` 的 `Makefile` 包含機制創建的 `rules` 文件更新爲 dh 語法，參看下文並理解各 `DEB_*` 配置變量。

  - `/usr/share/doc/cdbs/cdbs-doc.pdf.gz` 的本地副本

  - The Common Debian Build System (CDBS), FOSDEM 2009

- 如果你有一個不帶有 ``foo`.diff.gz` 文件的 `1.0` 格式的源代碼包，你可以通過創建 `debian/source/format` 文件並在其中添加 `3.0 (native)` 來將其更新爲新的 `3.0 (native)` 源代碼包格式。`debian` 目錄中的其他文件可以直接複製過來。

- 如果你有一個帶有 ``foo`.diff.gz` 文件的 `1.0` 格式的源代碼包，你可以通過創建 `debian/source/format` 文件並在其中添加 `3.0 (quilt)` 來將其更新爲新的 `3.0 (quilt)` 源代碼包格式。`debian` 目錄中的其他文件可以直接複製過來。如果需要，把 `filterdiff -z -x '*/debian/*' `foo`.diff.gz > big.diff` 生成的 `big.diff` 文件導入到 quilt 系統。[81]

- 如果它使用了其他的補丁系統，例如 `dpatch`、`dbs` 或 `cdbs`，使用 `-p0`、`-p1` 或 `-p2` 級別，使用 http://bugs.debian.org/581186 的 `deb3` 命令將其轉換到 `quilt` 系統。

- 如果它使用 dh 命令的 `--with quilt` 選項，或 dh_quilt_patch 和 dh_quilt_unpatch 命令，刪除它們並使其使用新的 `3.0 (native)` 源代碼包格式。

你應當查看 DEP - Debian Enhancement Proposals 並採納 ACCEPTED 建議。

當然你還需要按照 節 8.3, “新上游版本” 完成其他的步驟。

## 8.5. UTF-8 轉換

如果上游文檔採用了老式編碼，那麼將其轉換爲 UTF-8 不失爲一良方。

- 用 iconv(1) 來轉換普通文本文件的編碼。

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

- 使用 w3m(1) 來把 HTML 文件轉換爲 UTF-8 普通文本文件。 當你這樣做的時候，請確認在 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. 對更新套件的幾點提示

以下是對更新軟體包的幾點提示：

- 保留舊的 `changelog` 條目(看似顯然，但是總有可能把 `dch -i` 輸入爲 `dch`)。

- 已存在的 Debian 修改需要被重新校驗，去除上游已經接受的東西，除非有必要的原因，還要記錄尚未被上游接受的部分。

- 如果對編譯系統作出了修改(希望你已經在檢査上游變更時瞭解了這些)，那麼要在必要時更新 `debian/rules` 和 `debian/control` 編譯依賴關係。

- 檢查 Debian Bug Tracking System (BTS) 是否有人爲某些仍然未修復的 bug 提供了補丁。

- 檢查 `.changes` 文件以確保你正要上傳到正確的發行版、正確的列出BUG關閉 `Closes` 字段、`Maintainer` 和 `Changed-By` 字段相匹配，以及文件是否已經使用 GPG 簽署等。

[76] 要獲得需要的日期格式，使用 `LANG=C date -R`。

[77] 如果你用 `dch -r` 命令來使它成爲最後一筆更改， 請確保用編輯器顯式地保存 `changelog` 文件。

[78] 如果套件 ``foo`` 是使用舊的 `1.0` 格式的，可以在新解壓的原始碼目錄裏運行 `zcat /`path`/`to`/`foo`_`oldversion`.diff.gz|patch -p1` 來完成。

[79] 如果 uscan 命令下載並更新了原始碼，但沒有運行 uupdate 命令，你應該修正 `debian/watch` 檔案，使 URL 末尾後帶有 `debian uupdate`。

[80] 如果你的 sponsor 或其他維護者一定反對更新已有的打包風格，則不值得去爲此煩惱或爭論，總是有更重要的事要做。

[81] 你可能使用 splitdiff 命令將 `big.diff` 分割爲多個增量補丁。

章 7. 檢査套件中的錯誤 |  | 章 9. 上傳套件