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

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 開発者らからの主観的なヒント、アドバイス、ポインタです。あなたにとって一番うまくいくやり方を、どうぞご自由に選んでください。

6.1. debian/rules についてのベストプラクティス

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.

6.1.1. ヘルパースクリプト

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

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

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

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

6.1.2. パッチを複数のファイルに分離する

巨大で複雑なパッケージには、対処が必要なたくさんのバグが含まれているかもしれません。直接ソース中で大量のバグを修正し、あまり注意を払っていなかった場合、適用した様々なパッチを識別するのは難しいことになるでしょう。(全てではなく) 幾つか修正を取り入れた新しい開発元のバージョンへパッケージを更新する必要が出た場合、とても悲惨なことになります。(例えば、.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/rules の build ルールで 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 などです。

6.1.3. 複数のバイナリパッケージ

A single source package will often build several binary packages, either to provide several flavors of the same software (e.g., the vim source package) or to make several small packages instead of a big one (e.g., so the user can install only the subset needed, and thus save some disk space, see for example the lyx source package).

二つ目の例は、debian/rules で簡単に扱うことができます。ビルドディレクトリからパッケージの一時ツリーへ、適切なファイルを移動する必要があるだけです。これは、install または debhelper の dh_install を使ってできます。パッケージ間の依存関係を debian/control 内で正しく設定したのを忘れずに確認してください。

The first case is a bit more difficult since it involves multiple recompiles of the same software but with different configuration options. The vim source package is an example of how to manage this using a hand-crafted debian/rules file.

6.2. debian/control のベストプラクティス

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

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

6.2.1. パッケージ説明文の基本的なガイドライン

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

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

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

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

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

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

6.2.2. パッケージの概要、あるいは短い説明文

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

概要は、完全な文章ではなくパッケージを記述するフレーズとして機能します。ですので、句読点は不適切です: 追加の大文字や最後のピリオドは不要です。また、最初の不定冠詞や定冠詞 — "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

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

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

6.2.3. 長い説明文 (long description)

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

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

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

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)?

スペルミスや文法の間違いを避けるよう、注意してください。スペルチェックを確実に行ってください。ispell と aspell の双方に、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?

6.2.4. 開発元のホームページ

debian/control 中の Source セクションの Homepage フィールドへ、パッケージのホームページの URL を追加することをお勧めします。この情報をパッケージ説明文自身に追加するのは推奨されない (deprecated) であると考えられています。

6.2.5. バージョン管理システムの場所

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

6.2.5.1. Vcs-Browser

このフィールドの値は、指定したパッケージのメンテナンスに使われているバージョン管理システムのリポジトリのコピーがもしあれば、それを指し示す https:// URL である必要があります。

この情報は、パッケージに行われた最新の作業を閲覧したいエンドユーザにとって有用であるのが目的です (例: バグ追跡システムで pending とタグがつけられているバグを修正するパッチを探している場合)。

6.2.5.2. Vcs-*

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 アクセス可能なリポジトリを指すのではなく、匿名アクセスが可能なリポジトリを指すようにすることを意味します。

In the following example, an instance of the field for a Git repository of the vim package is shown. Note how the URL is in the https:// scheme (instead of ssh://). The use of the Vcs-Browser and Homepage fields described above is also shown.

Source: vim
<snip>
Vcs-Git: https://salsa.debian.org/vim-team/vim.git
Vcs-Browser: https://salsa.debian.org/vim-team/vim
Homepage: https://www.vim.org

6.3. debian/changelog のベストプラクティス

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

6.3.1. 役立つ changelog のエントリを書く

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

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

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

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

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

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

6.3.2. Selecting the upload urgency

The release team have indicated that they expect most uploads to unstable to use urgency=medium. That is, you should choose urgency=medium unless there is some particular reason for the upload to migrate to testing more quickly or slowly (see 不安定版からの更新). For example, you might select urgency=low if the changes since the last upload are large and might be disruptive in unanticipated ways.

6.3.3. changelog のエントリに関するよくある誤解

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

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

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

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

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

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

6.3.5. NEWS.Debian ファイルで changelog を補足する

パッケージの変更に関する重要なニュースは 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_installchangelogs が debian/NEWS ファイルをインストールしてくれます。

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

6.4. メンテナスクリプトのベストプラクティス

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 command -v install-docs > /dev/null; then ...

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

Using which is an acceptable alternative, since it is from the required debianutils package.

6.5. debconf による設定管理

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 の使い方についての一般的な考慮すべき事柄を含んでいます。

6.5.1. debconf を乱用しない

debconf が Debian に現れて以来、広く乱用され続けています。そして、debconf の乱用によって、ちょっとしたものをインストールする前に、大量の質問に答える必要があることに由来するいくつもの非難が Debian ディストリビューションに寄せられました。

Keep usage notes to where they belong: the NEWS.Debian, or README.Debian file. Only use notes for important notes that may directly affect the package usability. Remember that notes will always block the install until confirmed or bother the user by email.

Carefully choose the questions' priorities in maintainer scripts. See debconf-devel 7 for details about priorities. Most questions should use medium and low priorities.

6.5.2. 作者と翻訳者に対する雑多な推奨

6.5.2.1. 正しい英語を書く

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

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

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

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

6.5.2.2. 翻訳者へ丁寧に接する

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 debian-i18n@lists.debian.org 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) か debian-i18n@lists.debian.org にも問い合わせましょう。

6.5.2.3. 誤字やミススペルを修正する際に fuzzy を取る

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

6.5.2.4. インターフェイスについて仮定をしない

Templates text should not make reference to widgets belonging to some debconf interfaces. Sentences like If you answer Yes... have no meaning for users of graphical interfaces that use checkboxes for boolean questions.

文字列テンプレートは、説明文中でのデフォルト値について言及することも避けましょう。まず、ユーザによってそして、デフォルト値はメンテナの考え方によって違う場合があるからです (たとえば、debconf データベースが preseed で指定されている場合など)。

より一般的に言うと、ユーザの行動を参照させるのを避けるようにしましょう。単に事実を与えましょう。

6.5.2.5. 一人称を使わない

You should avoid the use of first person (I will do this... or We recommend...). The computer is not a person and the Debconf templates do not speak for the Debian developers. You should use neutral construction. Those of you who already wrote scientific publications, just write your templates like you would write a scientific paper. However, try using the active voice if still possible, like Enable this if ... instead of This can be enabled if....

6.5.2.6. 性差に対して中立であれ

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

6.5.3. テンプレートのフィールド定義

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

6.5.3.1. Type

6.5.3.1.1. string

ユーザがどのような文字列でも記述可能な自由記述形式の入力フィールドの結果。

6.5.3.1.2. password

ユーザにパスワードの入力を求めます。これを使う場合は注意して使ってください: ユーザが入力したパスワードは debconf のデータベースに書き込まれることに注意してください。おそらく、この値をデータベースから可能な限り早く消す必要があります。

6.5.3.1.3. boolean

true/false の選択です。注意点: true/false であって、yes/no ではありません...

6.5.3.1.4. select

複数の値から一つを選びます。選択するものは 'Choices' というフィールド名で指定されている必要があります。利用可能な値をコンマとスペースで区切ってください。以下のようになります: Choices: yes, no, maybe

選択肢が翻訳可能な文字列である場合、'Choices' フィールドは __Choices を使って翻訳可能であることを示しておくと良いでしょう。2つのアンダースコアは、各選択肢を分かれた文字列に分割してくれます。

po-debconf システムは、翻訳可能ないくつかの選択肢のみをマークする面白い機能を提供してくれます。例:

Template: foo/bar
Type: Select
#flag:translate:3
__Choices: PAL, SECAM, Other
_Description: TV standard:
 Please choose the TV standard used in your country.

この例では、他は頭文字から構成されていて翻訳できませんが、'Other' 文字列だけは翻訳可能です。上記では 'Other' だけが PO および POT ファイルに含めることができます。

debconf テンプレートのフラグシステムは、この様な機能をたくさん提供します。po-debconf 7 マニュアルページでは、これらの利用可能な機能をすべて列挙しています。

6.5.3.1.5. multiselect

select データ型とそっくりですが、ユーザが選択肢一覧からいくつでも項目を選べる (あるいはどれも選ばないこともできる) 点だけが違います。

6.5.3.1.6. note

本来質問ではありませんが、このデータ型が示すのはユーザに表示することができる覚え書きです。debconf はユーザが必ず参照するようにするため、多大な苦痛を与えることになる (キーを押すためにインストールを休止したり、ある場合にはメモをメールさえする) ので、ユーザが知っておく必要がある重要な記述にのみ使うべきです。

6.5.3.1.7. text

この type は現状では古すぎるものと考えられています: 使わないでください。

6.5.3.1.8. error

This type is designed to handle error messages. It is mostly similar to the note type. Front ends may present it differently (for instance, the dialog front end of cdebconf draws a red screen instead of the usual blue one).

何かを補正するためにユーザの注意を引く必要があるメッセージに対し、この type を使うのがお勧めです。

6.5.3.2. Description: short および extended 説明文

テンプレート説明文は 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 など) に応じた特別なルールについては、以下を読んでください。

6.5.3.3. Choices

This field should be used for select and multiselect types. It contains the possible choices that will be presented to users. These choices should be separated by commas.

6.5.3.4. Default

このフィールドはオプションです。これには、string、select あるいは multiselect のデフォルトでの答えが含まれます。multiselect テンプレートの場合、コンマで区切られた選択肢一覧が含まれます。

6.5.4. Template fields specific style guide

6.5.4.1. Type フィールド

特別な指定はありません。一点だけ、その前のセクションを参照して適切な type を使ってください。

6.5.4.2. Description フィールド

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

6.5.4.2.1. String/password テンプレート
  • 短い説明文は、プロンプトであってタイトルではありません。質問形式のプロンプト (IP アドレスは?) を避け、代わりに閉じていない形のプロンプト (IP アドレス:) を使ってください。コロン (:) の使用をお勧めします。
  • 拡張された説明文は、短い説明文を補足します。拡張の部分では、長い文章を使って同じ質問を繰り返すのではなく、何を質問されているのかを説明します。完全な文章を書いてください。簡潔な書き方は強く忌避されます。
6.5.4.2.2. Boolean テンプレート
  • The short description should be phrased in the form of a question, which should be kept short and should generally end with a question mark. Terse writing style is permitted and even encouraged if the question is rather long (remember that translations are often longer than original versions).
  • 繰り返しますが、特定のインターフェイスのウィジェットを参照するのを避けてください。このようなテンプレートで良くある間違いは、「はい」と答える形かどうかです。
6.5.4.2.3. Select/Multiselect
  • The short description is a prompt and not a title. Do not use useless "Please choose..." constructions. Users are clever enough to figure out they have to choose something... :)
  • 拡張された説明文は、短い説明文を完備します。これでは、利用可能な選択肢に言及することがあります。テンプレートが multiselect なものの場合、ユーザが選べる選択肢が 1 つではないことについても言及するかもしれません (インターフェイスが大抵これを明確にはしてくれますが)。
6.5.4.2.4. Note
  • 短い説明文はタイトルとして扱われます。
  • 拡張された説明文では、note のより詳細な説明を表示します。フレーズで、簡潔過ぎない書き方です。
  • Do not abuse debconf. Notes are the most common way to abuse debconf. As written in the debconf-devel manual page: it's best to use them only for warning about very serious problems. The NEWS.Debian or README.Debian files are the appropriate location for a lot of notes. If, by reading this, you consider converting your Note type templates to entries in NEWS.Debian or README.Debian, please consider keeping existing translations for the future.

6.5.4.3. Choices フィールド

もし Choise が頻繁に変わるようであれば、__Choices という使い方をするのを検討してください。これは個々の選択項目を単一の文字列に分割するので、翻訳作業者が作業を行うのを助けてくれると考えられています。

6.5.4.4. Default フィールド

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.

6.6. 国際化

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.

6.6.1. debconf の翻訳を取り扱う

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

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 マニュアルページを参照してください。

6.6.2. ドキュメントの国際化

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

どのようなサイズであれドキュメントをメンテナンスしている場合、翻訳作業者がソースコントロールシステムにアクセスできるのであれば、彼らの作業が楽になるでしょう。翻訳作業者が、ドキュメントの 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.

6.7. パッケージ化に於ける一般的なシチュエーション

6.7.1. autoconf/automake を使っているパッケージ

autoconf の config.sub および config.guess を最新に保ちつづけるのは、移植作業者、特により移行中の状況であるアーキテクチャの移植作業者にとって非常に重要です。autoconf や automake を使うあらゆるパッケージについてのとても素晴らしいパッケージ化における教訓が autotools-dev パッケージの /usr/share/doc/autotools-dev/README.Debian.gz にまとめられています。このファイルを読んで書かれている推奨に従うことを強くお勧めします。

6.7.2. ライブラリ

ライブラリは様々な理由から常にパッケージにするのが難しいです。ポリシーは、メンテナンスに楽にし、新しいバージョンが開発元から出た際にアップグレードを可能な限りシンプルであることを確保するため、多くの制約を課しています。ライブラリでの破損は、依存している何十ものパッケージの破損を招き得ます。

ライブラリのパッケージ化の良い作法が the library packaging guide にまとめられています。

6.7.3. ドキュメント化

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

あなたのパッケージが 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.

6.7.4. 特定の種類のパッケージ

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

  • 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 を参照してください。

6.7.5. アーキテクチャ非依存のデータ

大量のアーキテクチャ非依存データがプログラムと共にパッケージ化されるのは、良くあることではありません。例えば、音声ファイル、アイコン集、様々な模様の壁紙、その他一般的な画像ファイルです。このデータのサイズがパッケージの残りのサイズと比較して取るに足らないのであれば、おそらくは単一パッケージでひとまとめにしておくのがベストでしょう。

However, if the size of the data is considerable, consider splitting it out into a separate, architecture-independent package (_all.deb). By doing this, you avoid needless duplication of the same data into ten or more .debs, one per each architecture. While this adds some extra overhead into the Packages files, it saves a lot of disk space on Debian mirrors. Separating out architecture-independent data also reduces processing time of lintian (see パッケージチェック (lint) 用ツール) when run over the entire Debian archive.

6.7.6. ビルド中に特定のロケールが必要

ビルド中に特定のロケールを必要とする場合、こんな技を使えば一時ファイルを作成できます:

LOCPATH を /usr/lib/locale と同等のものに、そして LC_ALL を生成したロケールの名前に設定すれば、root にならなくても欲しいものが手に入ります。こんな感じです:

LOCALE_PATH=debian/tmpdir/usr/lib/locale
LOCALE_NAME=en_IN
LOCALE_CHARSET=UTF-8

mkdir -p $LOCALE_PATH
localedef -i $LOCALE_NAME.$LOCALE_CHARSET -f $LOCALE_CHARSET $LOCALE_PATH/$LOCALE_NAME.$LOCALE_CHARSET

# Using the locale
LOCPATH=$LOCALE_PATH LC_ALL=$LOCALE_NAME.$LOCALE_CHARSET date

6.7.7. 移行パッケージを deboprhan に適合するようにする

deborphan は、どのパッケージがシステムから安全に削除できるか、ユーザが検出するのを助けてくれるプログラムです; すなわち、どのパッケージも依存していないものです。デフォルトの動作は、使われていないライブラリを見つけ出すために libs と oldlibs セクションからのみ検索を行います。ですが、正しい引数を渡せば、他の使われていないパッケージを捕らえようとします。

For example, with --guess-dummy, deborphan tries to search all transitional packages which were needed for upgrade but which can now be removed. For that, it currently looks for the string dummy or transitional in their short description, though it would be better to search for both strings, as there are some dummy or transitional packages, which have other purposes.

ですので、あなたがそのようなパッケージを作る際には、 transitional dummy package を短い説明文に必ず追加してください。例を探す場合は、以下を実行してください: apt-cache search .|grep dummy または apt-cache search .|grep transitional

Also, it is recommended to adjust its section to oldlibs and its priority to optional in order to ease deborphan's job.

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

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

6.7.8.1. 手が入れられていないソース (Pristine source)

素のソース tarball (pristine source tarball) の特徴の定義は、.orig.tar.{gz,bz2,xz} は、開発元の作者によって公式に配布された tarball と 1 バイトたりとも違わない、というものです。 [1] これは、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/packagename_upstream-version.orig.tar.gz | tar xf -

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

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

6.7.8.2. upstream のソースをパッケージしなおす

パッケージは手が入っていない素のソース 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` <https://www.debian.org/doc/debian-policy/ch-source.html#s-debianrules>`__ に記述しているように、debian/rules に作業を繰り返してくれる get-orig-source ターゲットを追加するのも良い考えです。

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

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

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

  4. may use packagename-upstream-version+dfsg (or any atter suffix which is added to the tarball name) as the name of the top-level directory in its tarball. This makes it possible to distinguish pristine tarballs from repackaged ones.

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

6.7.8.3. バイナリファイルの変更

Sometimes it is necessary to change binary files contained in the original tarball, or to add binary files that are not in it. This is fully supported when using source packages in “3.0 (quilt)” format; see the dpkg-source1 manual page for details. When using the older format “1.0”, binary files can't be stored in the .diff.gz so you must store a uuencoded (or similar) version of the file(s) and decode it at build time in debian/rules (and move it in its official location).

6.7.9. デバッグパッケージのベストプラクティス

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.

6.7.9.1. Automatically generated debug packages

Debug symbol packages can be generated automatically for any binary package that contains executable binaries, and except for corner cases, it should not be necessary to use the old manually generated ones anymore. The package name for a automatic generated debug symbol package ends in -dbgsym.

The dbgsym packages are not installed into the regular archives, but in dedicated archives. That means, if you need the debug symbols for debugging, you need to add this archives to your apt configuration and then install the dbgsym package you are interested in. Please read https://wiki.debian.org/HowToGetABacktrace on how to do that.

6.7.9.2. Manual -dbg packages

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.7.10. メタパッケージのベストプラクティス

メタパッケージは、時間がかかる一貫したセットのパッケージをインストールするのを楽にしてくれる、ほぼ空のパッケージです。そのセットの全パッケージに依存することで、これを実現しています。APT の力のおかげで、メタパッケージのメンテナは依存関係を調整すればユーザのシステムが自動的に追加パッケージを得ることができます。自動的にインストールされていてメタパッケージから落とされたパッケージは、削除候補としてマークされます (そして aptitude によって自動的に削除もされます)。gnome と linux-image-amd64 は、メタパッケージの 2 つの例です (ソースパッケージ meta-gnome2 and linux-latest から生成されています)。

The long description of the meta-package must clearly document its purpose so that the user knows what they will lose if they remove the package. Being explicit about the consequences is recommended. This is particularly important for meta-packages that are installed during initial installation and that have not been explicitly installed by the user. Those tend to be important to ensure smooth system upgrades and the user should be discouraged from uninstalling them to avoid potential breakages.

[1]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.
[2]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.