第6章 パッケージ化のベストプラクティス

目次

6.1. debian/rules についてのベストプラクティス
6.1.1. ヘルパースクリプト
6.1.2. パッチを複数のファイルに分離する
6.1.3. 複数のバイナリパッケージ
6.2. debian/control のベストプラクティス
6.2.1. パッケージ説明文の基本的なガイドライン
6.2.2. パッケージの概要、あるいは短い説明文
6.2.3. 長い説明文 (long description)
6.2.4. 開発元のホームページ
6.2.5. バージョン管理システムの場所
6.2.5.1. Vcs-Browser
6.2.5.2. Vcs-*
6.3. debian/changelog のベストプラクティス
6.3.1. 役立つ changelog のエントリを書く
6.3.2. Selecting the upload urgency
6.3.3. changelog のエントリに関するよくある誤解
6.3.4. changelog のエントリ中のよくある間違い
6.3.5. NEWS.Debian ファイルで changelog を補足する
6.4. メンテナスクリプトのベストプラクティス
6.5. debconf による設定管理
6.5.1. debconf を乱用しない
6.5.2. 作者と翻訳者に対する雑多な推奨
6.5.2.1. 正しい英語を書く
6.5.2.2. 翻訳者へ丁寧に接する
6.5.2.3. 誤字やミススペルを修正する際に fuzzy を取る
6.5.2.4. インターフェイスについて仮定をしない
6.5.2.5. 一人称を使わない
6.5.2.6. 性差に対して中立であれ
6.5.3. テンプレートのフィールド定義
6.5.3.1. Type
6.5.3.1.1. string
6.5.3.1.2. password
6.5.3.1.3. boolean
6.5.3.1.4. select
6.5.3.1.5. multiselect
6.5.3.1.6. note
6.5.3.1.7. text
6.5.3.1.8. error
6.5.3.2. Description: short および extended 説明文
6.5.3.3. Choices
6.5.3.4. Default
6.5.4. Template fields specific style guide
6.5.4.1. Type フィールド
6.5.4.2. Description フィールド
6.5.4.2.1. String/password テンプレート
6.5.4.2.2. Boolean テンプレート
6.5.4.2.3. Select/Multiselect
6.5.4.2.4. Note
6.5.4.3. Choices フィールド
6.5.4.4. Default フィールド
6.6. 国際化
6.6.1. debconf の翻訳を取り扱う
6.6.2. ドキュメントの国際化
6.7. パッケージ化に於ける一般的なシチュエーション
6.7.1. autoconf/automake を使っているパッケージ
6.7.2. ライブラリ
6.7.3. ドキュメント化
6.7.4. 特定の種類のパッケージ
6.7.5. アーキテクチャ非依存のデータ
6.7.6. ビルド中に特定のロケールが必要
6.7.7. 移行パッケージを deboprhan に適合するようにする
6.7.8. .orig.tar.{gz,bz2,xz} についてのベストプラクティス
6.7.8.1. 手が入れられていないソース (Pristine source)
6.7.8.2. upstream のソースをパッケージしなおす
6.7.8.3. バイナリファイルの変更
6.7.9. デバッグパッケージのベストプラクティス
6.7.9.1. Automatically generated debug packages
6.7.9.2. Manual -dbg packages
6.7.10. メタパッケージのベストプラクティス

Debian's quality is largely due to the Debian Policy, which defines explicit baseline requirements that all Debian packages must fulfill. Yet there is also a shared history of experience which goes beyond the Debian Policy, an accumulation of years of experience in packaging. Many very talented people have created great tools, tools which help you, the Debian maintainer, create and maintain excellent packages.

この章では、Debian 開発者へのベストプラクティスをいくつか提供します。すべての勧めは単に勧めであり、要求事項やポリシーではありません。Debian 開発者らからの主観的なヒント、アドバイス、ポインタです。あなたにとって一番うまくいくやり方を、どうぞご自由に選んでください。

The following recommendations apply to the debian/rules file. Since debian/rules controls the build process and selects the files that go into the package (directly or indirectly), it's usually the file maintainers spend the most time on.

debian/rules でヘルパースクリプトを使う根拠は、多くのパッケージ間でメンテナらに共通のロジックを利用・共有させるようになるからです。メニューエントリのインストールについての問いを例にとってみましょう: ファイルを /usr/share/menu (必要であれば、実行形式のバイナリのメニューファイルの場合 /usr/lib/menu) に置き、メンテナスクリプトにメニューエントリを登録・解除するためのコマンドを追加する必要があります。これはパッケージが行う、非常に一般的なことです。なぜ個々のメンテナがこれらのすべてを自分で書き直し、時にはバグを埋め込む必要があるでしょう? また、メニューディレクトリが変更された場合、すべてのパッケージを変更する必要があります。

ヘルパースクリプトがこれらの問題を引き受けてくれます。ヘルパースクリプトの期待するやり方に従っているならば、ヘルパースクリプトはすべての詳細について考慮をします。ポリシーの変更はヘルパースクリプト中で行えます; そして、パッケージを新しいバージョンのヘルパースクリプトでリビルドする必要があるだけです。他に何の変更も必要ありません。

付録A Debian メンテナツールの概要 には、複数の異なったヘルパーが含まれています。もっとも一般的で (我々の意見では) ベストなヘルパーシステムは debhelper です。debmake のような、以前のヘルパーシステムはモノリシックでした: 使えそうなヘルパーの一部を取り出して選ぶことはできず、何を行うにもヘルパーを使う必要がありました。ですが、debhelper は、いくつもの分割された小さな dh_* プログラムです。たとえば、dh_installman は man ページをインストールして圧縮し、dh_installmenu は menu ファイルをインストールするなどします。つまり、debian/rules 内で使える部分では小さなヘルパースクリプトを使い、手製のコマンドを使うといった十分な柔軟性を与えてくれます。

debhelper(1) を読んで、パッケージに付属している例を参照すれば、debhelper を使い始めることができます。 dh-make パッケージ (dh-make 参照) の dh_make は、素のソースパッケージを debhelper化されたパッケージに変換するのに利用できます。ですが、この近道では個々の dh_* ヘルパーをわざわざ理解する必要がないので、満足できないでしょう。ヘルパースクリプトを使おうとするのであれば、そのヘルパーを使うこと、つまり前提と動作を学ぶのに時間を割く必要があります。

巨大で複雑なパッケージには、対処が必要なたくさんのバグが含まれているかもしれません。直接ソース中で大量のバグを修正し、あまり注意を払っていなかった場合、適用した様々なパッチを識別するのは難しいことになるでしょう。(全てではなく) 幾つか修正を取り入れた新しい開発元のバージョンへパッケージを更新する必要が出た場合、とても悲惨なことになります。(例えば、.diff.gz から) diff をすべて適用することもできませんし、開発元で修正されたバグごとにどのパッチをバックアウトするようにすればよいのか分かりません。

Fortunately, with the source format “3.0 (quilt)” it is now possible to keep patches separate without having to modify debian/rules to set up a patch system. Patches are stored in debian/patches/ and when the source package is unpacked patches listed in debian/patches/series are automatically applied. As the name implies, patches can be managed with quilt.

より古いソースフォーマット“1.0”を使っている場合でも、パッチを分割することは可能ですが、専用のパッチシステムを使う必要があります: パッチファイルは Debian パッチファイル (.diff.gz) 内に組み込まれ、通常 debian/ ディレクトリ内にあります。違いは、すぐに dpkg-source では適用されないが、debian/rulesbuild ルールで patch ルールへの依存を通じて適用されることだけです。逆に言うと、これらのパッチは unpatch ルールへの依存を通じて clean ルールで外されます。

quilt is the recommended tool for this. It does all of the above, and also allows one to manage patch series. See the quilt package for more information.

他にもパッチを管理するツールはあります。dpatch や、パッチシステムが統合されている cdbs などです。

以下のプラクティスは、debian/control ファイルに関するものです。パッケージ説明文についてのポリシーを補完します。

パッケージの説明文は、control ファイルの対応するフィールドにて定義されている様に、パッケージの概要とパッケージに関する長い説明文の両方を含んでいます。「パッケージ説明文の基本的なガイドライン」 では、パッケージ説明文の双方の部分についての一般的なガイドラインが記述されています。それによると、「パッケージの概要、あるいは短い説明文」 が概要に特化したガイドラインを提供しており、そして 「長い説明文 (long description)」 が説明文 (description) に特化したガイドラインを含んでいます。

パッケージの説明文は平均的なユーザーに向けて書く必要があります。平均的な人というのは、パッケージを使って得をするであろう人のことです。例えば、開発用パッケージであれば開発者向けですし、彼ら向けの言葉でテクニカルに記述することができます。より汎用的なアプリケーション、例えばエディタなどであれば、あまり技術的ではないユーザ向けに書く必要があります。

パッケージ説明文のレビューを行った結果、ほとんどのものがテクニカルである、つまり、技術に詳しくはないユーザに通じるようには書かれてはいないという結論に達しました。あなたのパッケージが、本当に技術に精通したユーザ用のみではない限り、これは問題です。

どうやって技術に詳しくはないユーザに対して書けばいいのでしょう? ジャーゴンを避けましょう。ユーザが詳しくないであろう他のアプリケーションやフレームワークへの参照を避けましょうー GNOME や KDE については、おそらくユーザはその言葉について知っているでしょうから構いませんが、GTK+ はおそらくダメです。まったく知識がないと仮定してみましょう。技術用語を使わねばならない場合は、説明しましょう。

客観的になりましょう。パッケージ説明文はあなたのパッケージの宣伝場所ではありません。あなたがそのパッケージをどんなに愛しているかは関係ありません。その説明文を読む人は、あなたが気にすることと同じことを気にはしないであろうことを覚えておいてください。

他のソフトウェアパッケージ、プロトコル名、標準規格、仕様の名前を参照する場合には、もしあれば正規名称を使いましょう。X Windows や X-Windows や X Window ではなく、X Window System あるいは X11 または X を使いましょう。GTK や gtk ではなく GTK+ を使いましょう。Gnome ではなく GNOME を使いましょう。Postscript や postscript ではなく PostScript を使いましょう。

説明文を書くことに問題があれば、 へそれを送ってフィードバックを求めるとよいでしょう。

ポリシーでは、概要行 (短い説明文) はパッケージ名を繰り返すのではなく、簡潔かつ有益なものである必要がある、となっています。

概要は、完全な文章ではなくパッケージを記述するフレーズとして機能します。ですので、句読点は不適切です: 追加の大文字や最後のピリオドは不要です。また、最初の不定冠詞や定冠詞 — "a", "an", or "the" を削る必要があります。つまり、例えば以下のようになります:

Package: libeg0
Description: exemplification support library

技術的に言えば、動詞のフレーズに対して、これは名詞のフレーズから文章を差し引いたものです。パッケージ要約をこの決まり文句に代入できるのがよい見つけ方です:

パッケージの名前概要を提供します。

関連パッケージ群は、概要を 2 つに分けた別の書き方をした方が良いでしょう。最初はその組一式の説明文で、その次はその組内でのパッケージの役割のサマリにします:

Package: eg-tools
Description: simple exemplification system (utilities)
			              
Package: eg-doc
Description: simple exemplification system - documentation

これらの要約が、手が加えられた決まり文句に続きます。パッケージ "" が、"プログラム一式 (役割)" あるいは "プログラム一式 - 役割" という要約を持つ場合、要素はフレーズにすべきで、決まり文句に合うようになります:

パッケージは、プログラム一式に対する役割を表しています。

長い説明文は、ユーザーがパッケージをインストールする前に利用可能な最初の情報です。ユーザーがインストールするか否かを決めるのに必要な情報を、すべて提供する必要があります。ユーザーがパッケージの概要を既に読んでいると仮定してください。

長い説明文は、完全な文章から成る必要があります。

長い説明文の最初の段落は、以下の質問に答えている必要があります: このパッケージは何をするの? ユーザが作業を完了するのに、どのタスクが役に立つの? ─ 技術寄りではない書き方でこれを記述するのが重要です。もちろんパッケージの利用者が必然的に技術者ではない限り、です。

The following paragraphs should answer the following questions: Why do I as a user need this package? What other features does the package have? What outstanding features and deficiencies are there compared to other packages (e.g., if you need X, use Y instead)? Is this package related to other packages in some way that is not handled by the package manager (e.g., is this the client for the foo server)?

スペルミスや文法の間違いを避けるよう、注意してください。スペルチェックを確実に行ってください。ispellaspell の双方に、debian/control ファイルをチェックするための特別なモードがあります:

ispell -d american -g debian/control
aspell -d en -D -c debian/control

通常、ユーザは以下のような疑問がパッケージ説明文で答えられることを期待しています:

  • パッケージは何をするの? 他のパッケージのアドオンだった場合、パッケージがアドオンであるということを概要文に書く必要があります。

  • なぜこのパッケージを使うべきなの? これは上記に関連しますが、同じではありません (これはメールユーザーエージェントです; クールで速く、PGP や LDAP や IMAP のインターフェイスがあり、X や Y や Z の機能があります)。

  • パッケージが直接インストールされるべきではないが、他のパッケージから引っ張ってこられる時には、付記しておく必要があります。

  • パッケージが実験的である、あるいは使われない方が良い他の理由がある場合、同様にここに記載する必要があります。

  • How is this package different from the competition? Is it a better implementation? more features? different features? Why should I choose this package?

debian/control には、バージョン管理システムの場所についての追加フィールドがあります。

Value of this field should be a string identifying unequivocally the location of the Version Control System repository used to maintain the given package, if available. * identifies the Version Control System; currently the following systems are supported by the package tracking system: arch, bzr (Bazaar), cvs, darcs, git, hg (Mercurial), mtn (Monotone), svn (Subversion). It is allowed to specify different VCS fields for the same package: they will all be shown in the PTS web interface.

この情報は、そのバージョン管理システムについて知識があり、VCS ソースから現在のバージョンパッケージを生成ユーザにとって有益であるよう意図されています。この情報の他の使い方としては、指定されたパッケージの最新の VCS バージョンを自動ビルドするなどがあるかもしれません。このため、フィールドによって指し示される場所は、バージョンに関係なく、(そのようなコンセプトをサポートしている VCS であれば) メインブランチを指すのが良いでしょう。また、指し示される場所は一般ユーザがアクセス可能である必要があります; この要求を満たすには SSH アクセス可能なリポジトリを指すのではなく、匿名アクセスが可能なリポジトリを指すようにすることを意味します。

以下の例では、vim パッケージの Subversion リポジトリに対するフィールドの例が挙げられています。(svn+ssh:// ではなく) svn:// スキーム中で URL がどのようになっているか、trunk/ ブランチをどのように指し示しているかに注意してください。上で挙げられた Vcs-Browser フィールドと Homepage フィールドの使い方も出ています。

  Source: vim
  Section: editors
  Priority: optional
  <snip>
  Vcs-Svn: svn://svn.debian.org/svn/pkg-vim/trunk/packages/vim
  Vcs-Browser: https://svn.debian.org/wsvn/pkg-vim/trunk/packages/vim
  Homepage: http://www.vim.org

以下のプラクティスは changelog ファイルに対するポリシーを補完します。

パッケージリビジョンに対する changelog エントリは、そのリビジョンでの変更それだけを記載します。最後のバージョンから行われた、重要な、そしてユーザに見える形の変更を記述することに集中しましょう。

何が変更されたかについて集中しましょう — 誰が、どうやって、何時なのか通常あまり重要ではありません。そうは言っても、パッケージ作成について明記すべき手助けをしてくれた人々 (例えば、パッチを送ってくれた人) を丁寧に明記するのを忘れないようにしましょう。

些細で明白な変更を詳細に書く必要はありません。複数の変更点を一つのエントリにまとめることもできます。逆に言えば、大きな変更をした場合には、あまりに簡潔にしすぎないようにしましょう。プログラムの動作に影響を与える変更がある場合には、特に確認しておきましょう。詳細な説明については、README.Debian ファイルを使ってください。

平易な英語を使いましょう。そうすれば読者の大半が理解できます。バグをクローズする変更を説明する際には略語や、テクニカルな言い方やジャーゴンを避けましょう。特に、技術的に精通していないと思われるユーザによって登録されたバグを閉じる際には気をつけましょう。礼儀正しく、断言をしないように。

時折、changelog エントリに変更したファイルの名前を頭に付けたくなることがあります。ですが、個々のすべての変更したファイルを一覧にする必要性はありません。特に変更点が小さくて繰り返される場合です。ワイルドカードを使いましょう。

バグに触れる際には、何も仮定しないようにしましょう。何が問題だったのか、どうやってそれが直されたのかについて言い、closes: #nnnnn の文字列を追加しましょう。詳細については 「新規アップロードでバグがクローズされる時」 を参照してください。

changelog エントリは、一般的なパッケージ化の事柄 (ほら、foo.conf を探しているなら /etc/blah にあるよ) を記載するべきではありません。何故なら、管理者やユーザは少なくとも Debian システム上でそのようなことがどのように扱われるかを多少は知らされているでしょうから。ですが、設定ファイルの場所を変更したのであれば、それは一言添えておくべきです。

changelog エントリでクローズされるバグは、実際にそのパッケージリビジョンで修正されたものだけにすべきです。changelog で関係ないバグを閉じるのは良くない習慣です。「新規アップロードでバグがクローズされる時」 を参照してください。

changelog エントリは、バグ報告者との各種の議論の場 (foo をオプション bar 付きで起動した際にはセグメンテーションフォルトは見られません; もっと詳しい情報を送ってください)、生命、宇宙、そして万物についての概要 (すいませんが、このアップロードに時間がかかったので風邪をひきました)、手助けの求め (このパッケージのバグ一覧は巨大です、手を貸してください) に使うべきではありません。そのようなことは、大抵の場合対象としている読者は気づくことが無く、パッケージで実際にあった変更点の情報について読みたい人々を悩ますことでしょう。どの様にバグ報告システムを使えばいいのかについて、詳細な情報は「バグへの対応」を参照してください。

正式なメンテナによるアップロードの changelog エントリの最初で、non-maintainer upload で修正されたバグを承認するのは、古い慣習です。今はバージョン管理を行っているので、NMU された changelog エントリを残しておいて自分の changelog エントリ中でその事実に触れるだけで十分です。

以下の例で、changelog エントリ中のよくある間違いや間違ったスタイルの例を挙げます。

  * Fixed all outstanding bugs.

これは、全く読み手に何も有用なことを教えてくれません。

  * Applied patch from Jane Random.

何についてのパッチですか?

  * Late night install target overhaul.

何をオーバーホールしてどうなったのですか? 深夜というのに言及しているのは、私たちにこのコードを信用するなと言いたいのですか?

  * Fix vsync fw glitch w/ ancient CRTs.

Too many acronyms (what does "fw" mean, "firmware"?), and it's not overly clear what the glitch was actually about, or how it was fixed.

  * This is not a bug, closes: #nnnnnn.

まず初めに、この情報を伝えるためにパッケージをアップロードする必要は、全くありません; 代わりにバグ追跡システムを使ってください。次に、何故この報告がバグではなかったのかについての説明がありません。

  * Has been fixed for ages, but I forgot to close; closes: #54321.

If for some reason you didn't mention the bug number in a previous changelog entry, there's no problem, just close the bug normally in the BTS. There's no need to touch the changelog file, presuming the description of the fix is already in (this applies to the fixes by the upstream authors/maintainers as well; you don't have to track bugs that they fixed ages ago in your changelog).

  * Closes: #12345, #12346, #15432

説明はどこ? 説明文を考えられないのなら、それぞれのバグのタイトルを入れるところから始めてください。

パッケージの変更に関する重要なニュースは NEWS.Debian ファイルにも書くことができます。このニュースは apt-listchanges のようなツールで、残りすべての changelog の前に表示されます。これは、ユーザにパッケージ内の著しい変更点について知らせるのに好ましいやり方です。インストール後にユーザが一旦戻って NEWS.Debian ファイルを参照できるので、debconf の notes を使うより良いです。そして、目立った変更点を README.Debian に列挙するより良いです。何故ならば、ユーザは容易にそのような注意書きを見逃すからです。

ファイル形式は debian changelog ファイルと同じですが、アスタリスク (*) を取って各ニュースを changelog に書くような簡潔な要約ではなく、必要に応じて完全な段落で記述してください。changelog のようにビルド中に自動的にはチェックされないので、ファイルを dpkg-parsechangelog を実行してチェックするのは良い考えです。実際の NEWS.Debian ファイルの例が、以下になります:

cron (3.0pl1-74) unstable; urgency=low

    The checksecurity script is no longer included with the cron package:
    it now has its own package, checksecurity. If you liked the
    functionality provided with that script, please install the new
    package.

 -- Steve Greenland <stevegr@debian.org>  Sat,  6 Sep 2003 17:15:03 -0500

NEWS.Debian ファイルは /usr/share/doc/package/NEWS.Debian.gz ファイルとしてインストールされます。圧縮されていて、Debian ネイティブパッケージ中でも常にこの名前です。debhelper を使う場合は、dh_installchangelogsdebian/NEWS ファイルをインストールしてくれます。

changelog ファイルと違って、毎回のリリースごとに NEWS.Debian ファイルを更新する必要はありません。何か特にユーザが知るべき目新しいことがあったときにのみ、更新してください。全くニュースがない場合、NEWS.Debian ファイルをパッケージに入れてリリースする必要はありません。便りが無いのは良い知らせ、です (No news is good news!)。

Maintainer scripts include the files debian/postinst, debian/preinst, debian/prerm and debian/postrm. These scripts take care of any package installation or deinstallation setup that isn't handled merely by the creation or removal of files and directories. The following instructions supplement the Debian Policy.

メンテナスクリプトは冪等でなければなりません。これは、通常は 1 回呼ばれるスクリプトが 2 回呼ばれた場合、何も悪いことが起きないのを保証する必要があるという意味です。

標準入出力はログの取得のためにリダイレクトされることがあります (例: パイプへ向けられる)。ですので、これらが tty であることに依存してはいけません。

質問や対話的な設定はすべて最小限に止めておく必要があります。必要になった時は、インターフェイスに debconf パッケージを使いましょう。どのような場合でも、質問は postinst スクリプトの configure 段階にのみ、配置することができます。

メンテナスクリプトは、できる限りシンプルなものにしておきましょう。我々は、あなたは純粋な POSIX シェルスクリプトを使っているものだと考えています。覚えておいて欲しいのですが、何かしら bash の機能が必要になったら、メンテナスクリプトは bash のシェバン行にしておく必要があります。スクリプトへ簡単にちょっとした変更を追加するのに debhelper を使えるので、Perl より POSIX シェル、あるいは Bash の方が好まれます。

メンテナスクリプトを変更したら、パッケージの削除や二重インストール、purge のテストを確認してください。purge されたパッケージが完全に削除されたことを確認してください。つまり、メンテナスクリプト中で直接/間接を問わず作成されたファイルを削除する必要があるということです。

コマンドの存在をチェックする必要がある場合は、このような感じで行います

if which install-docs > /dev/null; then ...

コマンド名を引数として渡すことで、$PATH の検索するのにこの関数を使うことができます。コマンドが見つかった場合は true (ゼロ) を返し、そうでない場合は false を返します。command -vtypewhich は POSIX に無いので、これがもっとも汎用性の高いやり方です。

which は、Required となっている debianutils パッケージにあるので、別解として利用可能ですが、ルートパーティションにありません。つまり、/usr/bin にあって /bin ではないので、/usr パーティションがマウントする前に走るスクリプトの中では使えないということです。ほとんどのスクリプトは、この問題を持つようなことはありませんが。

Debconf is a configuration management system that can be used by all the various packaging scripts (postinst mainly) to request feedback from the user concerning how to configure the package. Direct user interactions must now be avoided in favor of debconf interaction. This will enable non-interactive installations in the future.

debconf は素晴らしいツールですが、しばしば適当に扱われています。多くの共通する失敗は、debconf-devel(7) man ページに記載されています。これは、debconf を使うのを決めた時、あなたが読むべきものです。また、ここではベストプラクティスを記述しています。

これらのガイドラインは、ディストリビューションの一部 (例えば、インストールシステム) に関する、より明確な推奨と同様に、幾つかの書き方と体裁に関する推奨、そして debconf の使い方についての一般的な考慮すべき事柄を含んでいます。

ほとんどの Debian パッケージメンテナはネイティブの英語話者ではありません。ですので、正しいフレーズのテンプレートを書くのは彼らにとっては容易ではありません。

メーリングリストを利用してください (むしろ乱用してください)。テンプレートを査読してもらいましょう。

下手に書かれたテンプレートは、パッケージに対して、そしてあなたの作業に対して、さらには Debian それ自体にすら対して、悪い印象を与えます。

可能な限り技術的なジャーゴンを避けましょう。いくつかの用語があなたにとっては普通に聞こえても、他の人には理解不可能かもしれません。避けられない場合には、 (説明文を使って) 解説してみましょう。その場合には、冗長さとシンプルさのバランスを取るようにしましょう。

Debconf templates may be translated. Debconf, along with its sister package po-debconf, offers a simple framework for getting templates translated by translation teams or even individuals.

gettext ベースのテンプレートを使ってください。開発用のシステムに po-debconf をインストールしてドキュメントを読みましょう (man po-debconf が取っ掛かりとして良いでしょう)。

Avoid changing templates too often. Changing template text induces more work for translators, which will get their translation fuzzied. A fuzzy translation is a string for which the original changed since it was translated, therefore requiring some update by a translator to be usable. When changes are small enough, the original translation is kept in PO files but marked as fuzzy.

大本のテンプレートを変更する予定がある場合、po-debconf パッケージで提供されている、podebconf-report-po という名の通知システムを使って翻訳作業者にコンタクトを取ってください。ほとんどのアクティブな翻訳作業者たちはとても反応が良く、変更を加えたテンプレートに対応するための作業をしてくれ、あなたが追加でアップロードする必要を減らしてくれます。gettext ベースのテンプレートを使っている場合、翻訳作業者の名前とメールアドレスは PO ファイルのヘッダに表示されており、podebconf-report-po によって使われます。

このユーティリティの使い方のお勧めの使い方:

cd debian/po && podebconf-report-po --call --languageteam --withtranslators --deadline="+10 days"

This command will first synchronize the PO and POT files in debian/po with the template files listed in debian/po/POTFILES.in. Then, it will send a call for new translations, in the mailing list. Finally, it will also send a call for translation updates to the language team (mentioned in the Language-Team field of each PO file) as well as the last translator (mentioned in Last-translator).

翻訳作業者に締切りを伝えるのは常にお勧めです。それによって、彼らは作業を調整できます。いくつかの翻訳作業チームは形式化された翻訳/レビュープロセスを整えており、10 日未満の猶予は不合理であると考えられています。より短い猶予期間は強すぎるプレッシャーを翻訳チームに与えるので、非常に些細な変更点に対してのみに留めるべきです。

迷った場合は、該当の言語の翻訳チーム (debian-l10n-xxxxx@lists.debian.org) か にも問い合わせましょう。

debconf テンプレートの文章が修正されて、その変更が翻訳に影響しない確信している場合には、翻訳作業者を労って翻訳文を fuzzy を取り除いてください。

そうしないと、翻訳作業者が更新をあなたに送るまでテンプレート全体は翻訳されていない状態になります。

翻訳をfuzzy ではなくすために、(po4a パッケージの一部である)msguntypot を使うことができます。

  1. POT ファイルと PO ファイルを再生成する。

    debconf-updatepo
  2. POT ファイルのコピーを作成する。

    cp templates.pot templates.pot.orig
  3. すべての PO ファイルのコピーを作成する。

    mkdir po_fridge; cp *.po po_fridge
  4. debconf テンプレートファイルを誤字修正のために変更する。

  5. POT ファイルと PO ファイルを再生成する (もう一度)。

    debconf-updatepo

    この時点では、typo 修正はすべての翻訳を fuzzy にしており、この残念な変更はメインディレクトリの PO ファイルと fridge の PO ファイルのみに適用されている。ここではどの様にしてこれを解決するかを示す。

  6. fuzzy になった翻訳を捨て、fridge から作り直す。

    cp po_fridge/*.po .
  7. 手動で PO ファイルと新しい POT ファイルをマージするが、不要な fuzzy を考慮に入れる。

    msguntypot -o templates.pot.orig -n templates.pot *.po
  8. ゴミ掃除。

    rm -rf templates.pot.orig po_fridge

As a way of showing our commitment to our diversity statement, please use gender-neutral constructions in your writing. This means avoiding pronouns like he/she when referring to a role (like "maintainer") whose gender is unknown. Instead, you should use the plural form (singular they).

この章の情報は、ほとんどを debconf-devel(7) マニュアルページから得ています。

テンプレート説明文は 2 つのパートに分かれます: short と extended です。短い説明文 (short description) はテンプレートの Description: 行にあります。

短い説明文は、ほとんどの debconf インターフェイスに適用するように、短く (50 文字程度に) しておく必要があります。通常、翻訳はオリジナルよりも長くなる傾向にあるので、短くすることは翻訳作業者を助けます。

The short description should be able to stand on its own. Some interfaces do not show the long description by default, or only if the user explicitly asks for it or even do not show it at all. Avoid things like: "What do you want to do?"

短い説明文は完全な文章である必要はありません。これは文章を短くしておき、効率的に推奨を行うためです。

拡張された説明文 (extended description) は、短い説明文を一語一句繰り返しをしてはなりません。長い説明文章を思いつかなければ、まず、もっと考えてください。debian-devel に投稿しましょう。助けを求めましょう。文章の書き方講座を受講しましょう! この拡張された説明文は重要です。もし、まったく何も思いつかなければ、空のままにしておきましょう。

拡張された説明文は完全な文章である必要があります。段落を短くしておくのは可読性を高めます。同じ段落で 2 つの考えを混ぜてはいけません。代わりに別の段落を書きます。

あまり冗長にしないようにしてください。ユーザは長すぎる画面を無視しようとします。経験からすると、20 行が越えてはならない境界です。何故ならば、クラシックなダイアログインターフェイスでは、スクロールする必要がでてくることになり、そして多くの人がスクロールなどしないからです。

拡張された説明文では、質問を含めては決していけません

テンプレートの type (string、boolean など) に応じた特別なルールについては、以下を読んでください。

以下は、テンプレートの型に応じて適切な Description (short および extended) を書くための特別な指示です。

If the default value for a select template is likely to vary depending on the user language (for instance, if the choice is a language choice), please use the _Default trick, documented in po-debconf(7).

This special field allows translators to put the most appropriate choice according to their own language. It will become the default choice when their language is used while your own mentioned Default Choice will be used when using English.

Do not use an empty default field. If you don't want to use default values, do not use Default at all.

If you use po-debconf (and you should; see 「翻訳者へ丁寧に接する」), consider making this field translatable, if you think it may be translated.

geneweb パッケージのテンプレートを例にとってみましょう:

Template: geneweb/lang
Type: select
__Choices: Afrikaans (af), Bulgarian (bg), Catalan (ca), Chinese (zh), Czech (cs), Danish (da), Dutch (nl), English (en), Esperanto (eo), Estonian (et), Finnish (fi), French (fr), German (de), Hebrew (he), Icelandic (is), Italian (it), Latvian (lv), Norwegian (no), Polish (pl), Portuguese (pt), Romanian (ro), Russian (ru), Spanish (es), Swedish (sv)
# This is the default choice. Translators may put their own language here
# instead of the default.
# WARNING : you MUST use the ENGLISH NAME of your language
# For instance, the French translator will need to put French (fr) here.
_Default: English[ translators, please see comment in PO files]
_Description: Geneweb default language:

Note the use of brackets, which allow internal comments in debconf fields. Also note the use of comments, which will show up in files the translators will work with.

The comments are needed as the _Default trick is a bit confusing: the translators may put in their own choice.

This section contains global information for developers to make translators' lives easier. More information for translators and developers interested in internationalization are available in the Internationalisation and localisation in Debian documentation.

移植作業者同様に、翻訳作業者は難しい課題を抱えています。多くのパッケージについて作業を行い、多くの異なったメンテナと共同作業をする必要があります。さらには、ほとんどの場合、彼らはネイティブな英語話者ではないので、あなたは特に忍耐強くあらねばいけないでしょう。

The goal of debconf was to make package configuration easier for maintainers and for users. Originally, translation of debconf templates was handled with debconf-mergetemplate. However, that technique is now deprecated; the best way to accomplish debconf internationalization is by using the po-debconf package. This method is easier both for maintainer and translators; transition scripts are provided.

po-debconf を使うと、翻訳は .po ファイルに収められます (gettext による翻訳技術からの引き出しです)。特別なテンプレートファイルには、元の文章と、どのフィールドが翻訳可能かがマークされています。翻訳可能なフィールドの値を変更すると、debconf-updatepo を呼び出すことで、翻訳作業者の注意が必要なように翻訳にマークがされます。そして、生成時には dh_installdebconf プログラムが、テンプレートに加え、最新の翻訳をバイナリパッケージに追加するのに必要となる魔法について、すべての面倒を見ます。詳細は po-debconf(7) マニュアルページを参照してください。

ドキュメントの国際化はユーザにとって極めて重要ですが、多くの労力がかかります。この作業をすべて除去する方法はありませんが、翻訳作業者を気楽にはできます。

どのようなサイズであれドキュメントをメンテナンスしている場合、翻訳作業者がソースコントロールシステムにアクセスできるのであれば、彼らの作業が楽になるでしょう。翻訳作業者が、ドキュメントの 2 つのバージョン間の違いを見ることができるので、例えば、何を再翻訳すればいいのかがわかるようになります。翻訳されたドキュメントは、翻訳作業がどのソースコントロールリビジョンをベースにしているのかという記録を保持しておくことをお勧めします。debian-installer パッケージ中の doc-check では興味深いシステムが提供されています。これは、翻訳すべき現在のリビジョンのファイルに対する構造化されているコメントを使って、指定されたあらゆる言語の翻訳状況の概要を表示し、翻訳されたファイルについては、翻訳がベースにしているオリジナルのファイルのリビジョンを表示します。自分の VCS 領域でこれを導入して利用した方が良いでしょう。

If you maintain XML or SGML documentation, we suggest that you isolate any language-independent information and define those as entities in a separate file that is included by all the different translations. This makes it much easier, for instance, to keep URLs up to date across multiple files.

Some tools (e.g. po4a, poxml, or the translate-toolkit) are specialized in extracting the translatable material from different formats. They produce PO files, a format quite common to translators, which permits seeing what needs to be re-translated when the translated document is updated.

ドキュメント化のポリシーに忘れず従ってください。

あなたのパッケージが XML や SGML から生成されるドキュメントを含んでいる場合、XML や SGML のソースをバイナリパッケージに含めてリリースしないことをお勧めします。ユーザがドキュメントのソースを欲しい場合には、ソースパッケージを引っ張ってくれば良いのです。

ポリシーではドキュメントは HTML 形式でリリースされるべきであると定めています。我々は、もし手がかからないで問題ない品質の出力が可能であれば、ドキュメントを PDF 形式とテキスト形式でもリリースすることをお勧めしています。ですが、ソースの形式が HTML のドキュメントを普通のテキスト版でリリースするのは、大抵の場合は適切ではありません。

リリースされたメジャーなマニュアルは、インストール時にdoc-baseで登録されるべきです。詳細については、doc-base パッケージのドキュメントを参照してください。

Debian ポリシー (12.1 章) では、マニュアルページはすべてのプログラム・ユーティリティ・関数に対して付属すべきであり、設定ファイルのようなその他のものについては付属を提案を示しています。もし、あなたがパッケージングをしているものがそのようなマニュアルページを持っていない場合は、パッケージに含めるために記述を行い、開発元 (upstream) へ送付することを検討してください。

The manpages do not need to be written directly in the troff format. Popular source formats are DocBook, POD and reST, which can be converted using xsltproc, pod2man and rst2man respectively. To a lesser extent, the help2man program can also be used to write a stub.

いくつかの特定の種類のパッケージは、特別なサブポリシーと対応するパッケージ化ルールおよびプラクティスを持っています:

  • Perl related packages have a Perl policy; some examples of packages following that policy are libdbd-pg-perl (binary perl module) or libmldbm-perl (arch independent perl module).

  • Python related packages have their Python policy; see /usr/share/doc/python/python-policy.txt.gz in the python package.

  • Emacs 関連パッケージには、emacs ポリシーがあります。

  • Java 関連パッケージには、java ポリシーがあります。

  • OCaml related packages have their own policy, found in /usr/share/doc/ocaml/ocaml_packaging_policy.gz from the ocaml package. A good example is the camlzip source package.

  • XML や SGML DTD を提供しているパッケージは、sgml-base-doc パッケージ中の推奨に従わねばなりません。

  • lisp パッケージは、パッケージ自身を common-lisp-controller に登録する必要があります。これについては、/usr/share/doc/common-lisp-controller/README.packaging を参照してください。

オリジナルのソース tarball には 2 種類あります: 手が入れられていない素のソース (Pristine source) と再パッケージした開発元のソース (repackaged upstream source) です。

素のソース tarball (pristine source tarball) の特徴の定義は、.orig.tar.{gz,bz2,xz} は、開発元の作者によって公式に配布された tarball と 1 バイトたりとも違わない、というものです。[6] これは、Debian diff 内に含まれているDebian バージョンと開発元のバージョン間のすべての違いを簡単に比較するのにチェックサムを使えるようになります。また、オリジナルのソースが巨大な場合、既に upstream の tarball を持っている upstream の作者と他の者は、あなたのパッケージを詳細に調査したい場合、ダウンロード時間を節約できます。

There are no universally accepted guidelines that upstream authors follow regarding the directory structure inside their tarball, but dpkg-source is nevertheless able to deal with most upstream tarballs as pristine source. Its strategy is equivalent to the following:

  1. 以下のようにして空の一時ディレクトリに tarball を展開します

    zcat path/to/パッケージ名_開発元のバージョン.orig.tar.gz | tar xf -
    
  2. もし、この後で、一時ディレクトリが 1 つのディレクトリ以外含まず他にどのファイルも無い場合、dpkg-source はそのディレクトリを パッケージ名-開発元のバージョン(.orig) にリネームします。tarball 中の最上位のディレクトリ名は問題にはされず、忘れられます。

  3. それ以外の場合、upstream の tarball は共通の最上位ディレクトリ無しでパッケージされなくては いけません (upstream の作者よ、恥を知りなさい!)。この場合、dpkg-source は一時ディレクトリそのものパッケージ名-開発元のバージョン(.orig) へリネームします。

パッケージは手が入っていない素のソース tarball と共にアップロードすべきですが、それが可能ではない場合が色々とあります。upstream がソースを gzip 圧縮した tarball を全く配布していない場合や、upstream の tarball が DFSG-free ではない、あなたがアップロード前に削除しなければならない素材を含んでいる場合がこれにあたります。

この様な場合、開発者は適切な .orig.tar.{gz,bz2,xz} ファイルを自身で準備する必要があります。この様な tarball を、再パッケージした開発元のソース (repackaged upstream source) と呼びます。再パッケージした開発元のソースでは Debian ネイティブパッケージとは違うことに注意してください。再パッケージしたソースは、Debian 固有の変更点は分割された .diff.gz または .debian.tar.{gz,bz2,xz} のままであり、バージョン番号は 開発元のバージョンdebian リビジョン から構成されたままです。

開発元が、原則的にはそのままの形で使える .tar.{gz,bz2,xz} を配布していたとしても再パッケージをしたくなるという場合がありえます。最も明解なのは、tar アーカイブを再圧縮することや upstream のアーカイブから純粋に使われていないゴミを削除することで、非常に容量を節約できる時です。ここで慎重になって頂きたいのですが、ソースを再パッケージする場合は、決定を貫く用意をしてください。

.orig.tar.{gz,bz2,xz} についてのベストプラクティス

  1. ソースパッケージの由来をドキュメントにすべきです。どうやってソースを得たのかという詳細情報が得たのか、どの様にすれば再生成できるのかを debian/copyright で提供しましょう。ポリシーマニュアルで、メイン構築スクリプト: debian/rules に記述しているように、debian/rules に作業を繰り返してくれる get-orig-source ターゲットを追加するのも良い考えです。

  2. 開発元の作者由来ではないファイルや、あなたが内容を変更したファイルを含めるべきではありません[7]

  3. 法的理由から不可能であるものを除いて、開発元の作者が提供しているビルドおよび移植作業環境を完全に保全すべきです。例えば、ファイルを省略する理由として MS-DOS でのビルドにしか使われないから、というのは十分な理由にはなりません。同様に、開発元から提供されている Makefile を省略すべきではありません。たとえ debian/rules が最初にすることが configure スクリプトを実行してそれを上書きすることであったとしても、です。

    (理由: Debian 以外のプラットフォームのためにソフトウェアをビルドする必要がある Debian ユーザが、開発元の一次配布先を探そうとせずに Debian ミラーからソースを取得する、というのは普通です)。

  4. tarball の最上位ディレクトリの名前として パッケージ名-開発元のバージョン.orig を使うべきです。これは、大元の使用されていない tarball と再パッケージしたものを判別できるようにしてくれます。

  5. gzip あるいは bzip で最大限圧縮されるべきです。

A debug package is a package that contains additional information that can be used by gdb. Since Debian binaries are stripped by default, debugging information, including function names and line numbers, is otherwise not available when running gdb on Debian binaries. Debug packages allow users who need this additional debugging information to install it without bloating a regular system with the information.

The debug packages contain separated debugging symbols that gdb can find and load on the fly when debugging a program or library. The convention in Debian is to keep these symbols in /usr/lib/debug/path, where path is the path to the executable or library. For example, debugging symbols for /usr/bin/foo go in /usr/lib/debug/usr/bin/foo, and debugging symbols for /usr/lib/libfoo.so.1 go in /usr/lib/debug/usr/lib/libfoo.so.1.

Before the advent of the automatic dbgsym packages, debug packages needed to be manually generated. The name of a manual debug packages ends in -dbg. It is recommended to migrate such old legacy packages to the new dbgsym packages whenever possible. The procedure to convert your package is described in https://wiki.debian.org/AutomaticDebugPackages but the gist is to use the --dbgsym-migration='pkgname-dbg (<< currentversion~)' switch of the dh_strip command.

However, sometimes it is not possible to convert to the new dbgsym packages, or you will encounter the old manual -dbg packages in the archives, so you might need to deal with them. It is not recommended to create manual -dbg packages for new packages, except if the automatic ones won't work for some reason.

One reason could be that debug packages contains an entire special debugging build of a library or other binary. However, usually separating debugging information from the already built binaries is sufficient and will also save space and build time.

This is the case, for example, for debugging symbols of Python extensions. For now the right way to package Python extension debug symbols is to use -dbg packages as described in https://wiki.debian.org/Python/DbgBuilds.

To create -dbg packages, the package maintainer has to explicitly specify them in debian/control.

The debugging symbols can be extracted from an object file using objcopy --only-keep-debug. Then the object file can be stripped, and objcopy --add-gnu-debuglink used to specify the path to the debugging symbol file. objcopy(1) explains in detail how this works.

デバッグパッケージは、そのパッケージがデバッグシンボルを提供するパッケージに依存する必要があり、この依存関係はバージョン指定が必要であるということに注意してください。以下のような例になります:

Depends: libfoo (= ${binary:Version})

The dh_strip command in debhelper supports creating debug packages, and can take care of using objcopy to separate out the debugging symbols for you. If your package uses debhelper/9.20151219 or newer, you don't need to do anything. debhelper will generate debug symbol packages (as package-dbgsym) for you with no additional changes to your source package.



[6] We cannot prevent upstream authors from changing the tarball they distribute without also incrementing the version number, so there can be no guarantee that a pristine tarball is identical to what upstream currently distributing at any point in time. All that can be expected is that it is identical to something that upstream once did distribute. If a difference arises later (say, if upstream notices that they weren't using maximal compression in their original distribution and then re-gzip it), that's just too bad. Since there is no good way to upload a new .orig.tar.{gz,bz2,xz} for the same version, there is not even any point in treating this situation as a bug.

[7] As a special exception, if the omission of non-free files would lead to the source failing to build without assistance from the Debian diff, it might be appropriate to instead edit the files, omitting only the non-free parts of them, and/or explain the situation in a README.source file in the root of the source tree. But in that case please also urge the upstream author to make the non-free components easier to separate from the rest of the source.