Debian JP Project

[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ 7 ] [ 8 ] [ 9 ] [ 10 ] [ 11 ] [ 12 ] [ A ] [ B ] [ C ] [ D ] [ E ] [ F ] [ G ] [ next ]

Debian ポリシーマニュアル
Chapter 4 - ソースパッケージ

4.1 基準への準拠

ソースパッケージには、あなたのパッケージが最後の更新の際にパッケージのコンパイルで準拠した、その時点で最新のパッケージング基準のバージョンを指定すべきです。

この情報は、あなたのパッケージがあまりにも旧式になってしまったときに自動的にバグレポートを提出するのに使われます。

このバージョンは Standards-Version コントロールフィールドで指定されます。Standards-Version フィールドの書式は Standards-Version, Section 5.6.11 で記載されています。

常に最新のポリシーマニュアルをチェックしておきましょう。あなたが過去にパッケージしたものがあって、それが古くなってしまっているなら特に必要です。その上で必要があればパッケージのアップデートを行って下さい。あなたのパッケージが新しい基準 [13] に則った際には、ソースパッケージの Standards-Version を変更してリリースするべきです。

4.2 パッケージ同士の依存関係

ソースパッケージには、ビルドするためにインストールされていなければならない、またはインストールされていてはいけないようなバイナリパッケージが明記されているべきです。例えば特定のコンパイラでないとビルドができない場合、ビルド時依存としてそのコンパイラが指定されているべきです。

しかしコンパイルに最小限必要なパッケージ (例えば C や C++ で書かれた "Hello World!" のようなプログラムをコンパイル、リンクし、 Debian パッケージ化するために必要なもの) までビルド時依存のものとして指定する必要はありません。このような場合に必要となるパッケージは build-essential と呼ばれ、build-essential パッケージに収録されているファイル /usr/share/doc/build-essential/list [14] にリストアップされています。

ビルド時依存のパッケージを指定する場合、目的のパッケージをビルドするのに直接必要であるもののみをリストアップするべきです。ビルド時依存として挙げたパッケージが依存しているという理由でパッケージを列挙する必要はありません [15]。

ビルド時の依存関係が指定されている場合、essential パッケージ、build-essential パッケージ、及び依存関係を満たすためのパッケージが全て (それらのパッケージが依存している物も含めて) 揃っているシステムでパッケージのビルドができなければいけません。このことは、依存関係が正しく満たされている場合に、間違っていたり矛盾を含んだパッケージを作り出さないよう、ビルド時依存に対するバージョン番号が厳密に指定されるべきであることを意味します。

パッケージ間の関連性の宣言, Chapter 7 に技術的詳細が記載されています。

4.3 アップストリームのソースへの変更

ソースコードへの変更が Debian システムでの固有の必要によるものでないなら、アップストリームの作者にその作者たちが望む形でその変更を含めることができるよう、その変更を送るべきです。

パッケージを Debian もしくは Linux 向けに修正する必要があり、アップストリームのソースがそれを行う手段を提供していない場合、そのような手段を追加すべきです。(例えば autoconf によるテストや #define 等) そしてデフォルトが修正前と同じになっているようなパッチをアップストリームの作者に送ります。そうすれば簡単にあなたの debian/rules かどこか適当なところでデフォルトを置きかえることができます。

configure ユーティリティには正しくアーキテクチャを指定できる文字列を検出させるようにすべきです (具体的にはアーキテクチャ指定のための文字列, Section 11.1 を参照)。

もし、GNU の configure スクリプトが作る Makefile を修正する必要にせまられた場合、直接 Makefile に手を加えずに .in ファイルを変更しましょう。こうすることでユーザによるパッケージの再ビルドが可能となります。あなたが configure を行ない、その後 Makefile を変更した場合、誰もその後であなたが加えた変更をなくさずにパッケージの再ビルドすることができなくなってしまいます。

4.4 Debian changelog: `debian/changelog`

Debian 版のパッケージの変更は全て簡潔に Debian changelog ファイル debian/changelog [16] に記載すべきです。これには上流の版に加えた Debian パッケージ向けの変更 [17]、およびパッケージに対するそれ以外の修正や更新を記載します。

この debian/changelog のフォーマットは、パッケージのどのバージョンを現在ビルド中なのか、及びその他のリリース特有の情報を、パッケージビルドツールが認識できるようになっています。

この書式は次に示すものがひとつらなりになったものです。

     パッケージ名 (バージョン) ディストリビューション; urgency=緊急度
     	    
       * 変更内容
         変更内容の続き
     	    
       * また別の変更内容
     	    
      -- メンテナ名 <電子メールアドレス>[空白二個]日付

package と version はソースパッケージの名前とバージョンです。

distribution(s) には、このバージョンがアップロードされるときにインストールされるディストリビューションがリストされます - これらは、.changes ファイルの Distribution フィールドにコピーされます。 Distribution, Section 5.6.14 をご覧ください。

urgency は、アップロード時の .changes ファイルの Urgency フィールドとして使われる値です。コンマを含む値を使用することはできません。 dpkg の changelog フォーマットでは、コンマは keyword=value の各設定を分離するために使用されています (しかしながら、現在のところ keywordとして有効なものは urgency だけです)。

詳細な変更点は、実際には最低二つのスペースではじまる一連の行に記されていればいいのですが、慣習的に各変更箇所はアスタリスクと分離のためのスペースで始め、継続行はインデントし、はじめの箇所が分かるような文章にしておきます。望むのであれば、一連の変更箇所を分離するのに空行が使用できます。

このアップロードがバグトラッキングシステム (BTS) で記録されたバグを修正するものならば、changelog 中に closes: Bug#nnnnn [18] の文字列を含めることで、パッケージが Debian アーカイブに収録された時点でバグが自動的に閉じられます。

changelog ファイルに記載するメンテナの名前と電子メールアドレスはこのバージョンをアップロードした人について記されているべきです。それは、必ずしも通常のパッケージ管理者である必要は ありません [19]。ここでの情報は、.changes ファイルの Changed-By (Changed-By, Section 5.6.4 参照) フィールドにコピーされ、その後アップロードの完了時に通知を送るために使用します。

日付 は以下のフォーマット [20] (RFC2822 および RFC5322 と互換で、同じ意味をもちます) でなければいけません。以下に例を示します。

     day-of-week, dd month yyyy hh:mm:ss +zzzz

ここで、

day-of-week は Mon, Tue, Wed, Thu, Fri, Sat, Sun のいずれかです。
dd は、1 桁または 2 桁の月内の日付を示します (01-31)。
月は、Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec のうちのいずれかです。
yyyy は 4 桁の年を示します (e.g. 2010)
hh は 2 桁の 24 時間制の時刻です (00-23)
mm は 2 桁の分を示します (00-59)
ss は 2 桁の秒を示します (00-60)
+zzzz および -zzzz は国際標準時 (UTC) からの標準時間帯のずれを示します。 + は UTC より進んでいる (東にある) ことを、- は UTC より遅れている (西にある) ことを示します。最初の 2 桁は UTC からの 1 時間単位の差を、下位 2 桁は UTC からの追加の時差を示します。下位 2 桁は 00 と 59 の間でなければいけません。

このフォーマットは、数字によって表現されたタイムゾーンを含まなければならず、オプションとして、かっこに入ったコメントの形でタイムゾーン名かその省略形を付加することができます。

パッケージ名ではじまる最初の「タイトル」の行は、左詰めにしなければいけません。それに続く管理者、日付フィールドの詳細は正確に一つのスペースからはじめなければいけません。管理者の詳細と日付フィールドは、正確に二つのスペースによって区切られていなければいけません。

changelog 全体が UTF-8 でエンコードされていなければいけません。

バイナリパッケージ中に置かれる changelog ファイルの書式についてのより詳しい解説は Changelog ファイル, Section 12.7 を参照ください。

4.5 著作権表記: `debian/copyright`

各パッケージには、著作権と配布条件のライセンス文書が元のままの形式で /usr/share/doc/package/copyright に収録されていなければいけません (詳細は著作権関連情報, Section 12.5 参照)。また、パッケージの著作権を取り込む際の考慮事項については著作権に関する考慮, Section 2.3 を参照ください。

4.6 makefile でのエラーを捕捉する

make が makefile (あなたのパッケージの上流が用意した makefile も debian/rules も含む) で指定されたコマンドを呼び出す際には、sh を使います。このため、sh のエラー処理の出来が悪いという欠点が露呈してしまいます。あなたの makefile に、そこから呼び出されるコマンドの一つとして小さなスクリプトが含まれている場合、もし適切に手を打たなければエラーは何も検出されず、make は問題が起こった後ものんきに処理を続けてしまうでしょう。

一つ以上のシェルコマンド (これにはループの使用も該当します) を makefile 内のコマンドとして使うときにはいつでも、エラーが捕捉されているかどうか確かめなければなりません。ディレクトリを移ってあるプログラムを実行する、というような単純な複合コマンドでは、コマンドセパレータとしてセミコロンを使うのではなく、 && でつなげば十分でしょう。多くのループや条件式といったより複雑なコマンド群に対しては、実際にはこれらの小さなシェルスクリプトの一つを呼び出している makefile コマンドのそれぞれの先頭に独立した set -e を含めるべきです。

4.7 タイムスタンプ

メンテナは可能な限り上流のソースファイルの更新時刻をパッケージ中で変更しないでおくべきです[21]。

4.8 ソースパッケージに含まれるものに対する制限

ソースパッケージには、ハードリンク [22] 、デバイスファイル、ソケットファイル、及び setuid や setgid されたファイル [23] が含まれていてはいけません。

4.9 `debian/rules` - メイン構築スクリプト

このファイルは実行可能な makefile で、ソースからパッケージをコンパイルしバイナリパッケージを構築するためのパッケージ特有のレシピを含んでいます。

このファイルの先頭は #!/usr/bin/make -f という行でなければなりません。 make を明示的に実行するのではなく、 debian/rules という名前で実行できるようにする為です。つまり、make -f debian/rules args... と実行した場合と、./debian/rules args... と実行した場合が同じ結果でなければいけません。

以下のターゲットは、debian/rules に必要で、実装されていなければいけません。 - clean, binary, binary-arch, binary-indep, build build-arch および build-indep。これらのターゲットは、dpkg-buildpackage から呼ばれます。

対話型の debian/rules スクリプトは、そのパッケージの自動コンパイルを不可能にし、さらにメンテナ以外の人が同じバイナリパッケージを再構築するのを難しくします。ですから、全ての 必要なターゲット は非対話的でなくてはなりません。また、これらのターゲットによって呼び出されるターゲットも非対話的でなくてはなりません。

ターゲットは次の通りです。

build (必須)

build ターゲットはパッケージの構築 (ビルド)、すなわち全てのパッケージの非対話的な設定とコンパイルを行ないます。もしパッケージにビルド前の対話型の設定ルーチンがある場合は、Debian ソースパッケージは設定作業を行なった後でビルドするか (これは、設定を再びせずにバイナリパッケージをビルド出来るようにするためです)、設定ルーチンを非対話型になるように変更しなければいけません。アーキテクチャ固有の機能の検出が設定ルーチンで行われるようになっている場合は、後者の方が適切です。

いくつかのパッケージで、同一のソースツリーからそれぞれ違う二つのバイナリパッケージを生成する場合があります。 build ターゲットはそういう場合には対応できません。これらの場合は、それぞれの構築方法にしたがって、2 つまたはそれ以上のターゲット (build-a と build-b やその他) を使用するのがよいでしょう。そしてこの場合、単独の build はなにも実行しません。 binary ターゲットで、これらの可能な方法でパッケージを作成して、それぞれに対応したバイナリパッケージを生成することになります。

ルート権限が必要なことを build ターゲットで実行してはいけません。

また、build ターゲットの前に、 clean を走らせる必要があることはかまいません。以下を参照ください。

パッケージの設定ルーチンに長い時間がかかる時や、makefile の設計がまずい場合、または build の前に clean の実行が必要な場合には、ビルドプロセスの終了時に touch build を実行しておくのがよいでしょう。これによって、 debian/rules build が再度実行されたときに、プログラム全体を再構築しなくてすみます [24]。

build-arch (必須) build-indep (必須)

build-arch ターゲットでは、アーキテクチャ依存のバイナリパッケージ (これらのパッケージには、debian/control の Architecture フィールドに all 以外が指定されています) を作成するのに必要なすべての設定とコンパイル処理を実行しなければいけません。同様に build-indep ターゲットは、アーキテクチャ非依存のバイナリパッケージ (これらのパッケージでは、debian/control の Architecture フィールドの値は all です) を作成するのに必要なすべての設定とコンパイル処理を実行しなければいけません。 build ターゲットは、それらのターゲットに依存関係を指定するか、それらのターゲットを呼んだ時に行われる動作と同じ処理を行うべきです[25]。

build-arch と build-indep では、root 権限が必要なことを行ってはいけません。

binary (必須), binary-arch (必須), binary-indep (必須)

binary ターゲットは、ユーザがこれだけでソースパッケージから生成されるバイナリパッケージ (複数のこともあります) をビルドできるようなものでなければいけません。これらのすべてのターゲットは、非対話的に動作するものでなければなりません。 binary ターゲットは、二つの部分に分けられます: binary-arch は、特定のアーキテクチャ用のファイル、 binary-indep は、それ以外のものを生成します。

binary は、コマンドなしで単純に binary-arch と binary-indep に依存するようなパッケージであることは許されますし、また普通のパッケージではそのようになっています。

両方の binary-* ターゲットは、 build ターゲット、あるいは build-arch または build-indep がある場合にはいずれかの適切なほうに依存すべきです。このようにしておけば、もしパッケージビルド処理が済んでいないときはビルド処理が実施されます。そしてその後 dpkg-gencontrol を使ってコントロールファイルを作成し、dpkg-deb でビルドを行って関連したバイナリパッケージを生成し、それをトップレベルディレクトリの親ディレクトリ中に置くべきです。

binary-arch と binary-indep の両方のターゲットが 存在しなければいけません。このうち一方がなにも作成するものがない場合でも (アーキテクチャ依存、非依存に関わらずソースから一つのバイナリパッケージしか生成しない場合がこれに当たります) 、両方のターゲットが存在しなければなりませんし、また処理が成功したという扱いにしなければなりません。

binary ターゲットは、ルート権限で起動されなければ [26] いけません。

clean (必須)

build と binary ターゲットによる実行結果を元に戻します。ただし、binary ターゲットの実行により親ディレクトリに作成された出力ファイルはそのまま残します。このターゲットは、非対話的でなければいけません。

前の項で述べたように、build ファイルが build ターゲット処理の最後に touch されて作成されていた場合、そのファイルは、clean の最初の作業として削除するべきです。中断された clean の後に build が実行された場合、すべてが終了したと認識されてしまいかねないからです。

build ターゲットがルート権限で実行された後、及び binary ターゲットが実行された後には、clean ターゲットはルート権限で起動する必要があるかもしれません (例えば、build はディレクトリを作成することもあるからです)。

get-orig-source (オプション)

主要なアーカイブサイトから最新版のオリジナルソースパッケージを取得します (FTP や WWW経由)。これをオリジナルのソースの tar ファイル形式 (下記参照) に再構成し、現在のディレクトリに置きます。

このターゲットは、どのディレクトリからも実行してもかまいません。また残した一時ファイルを削除するよう気を遣うべきです。

このターゲットはオプションです。しかしできる限りつけた方がよいでしょう。

patch (オプション): このターゲットでは、ソースを修正可能とするための何らかの操作 (追加の上流のアーカイブの展開や、パッチの適用など) が必要な場合、それを実行します。dpkg-source -x の実行のみでは修正可能なソースが得られないパッケージの場合、利用を推奨します。ソースパッケージの処理: debian/README.source, Section 4.14 を参照ください。

build、binary 及び clean ターゲットはパッケージのトップディレクトリをカレントディレクトリとして実行されなければいけません。

公開されている、またはいないインターフェースのためや、パッケージ内部で使用するために debian/rules に他のターゲットを置くことは許されています。

パッケージを実際にビルドするマシンや、インストールの対象となるマシンのアーキテクチャは、 dpkg-architecture ユーティリティを使って make 変数を設定することによって決定されます。これにより、ホストアーキテクチャだけでなくパッケージのビルドをするマシンアーキテクチャの Debian 形式のアーキテクチャ指定文字列と GNU 形式のアーキテクチャ指定文字列を得ることができます。ビルドアーキテクチャとは、debian/rules が実行され、パッケージビルドが行われるアーキテクチャです。ホストアーキテクチャとは、生成されたパッケージがインストールされ、実行されるアーキテクチャです。これらは通常は同じですが、クロスコンパイル (あるアーキテクチャ向けのパッケージを異なったアーキテクチャのマシンでビルドする) の場合、異なっていても構いません。

次に、サポートされている make 変数を示します。

DEB_*_ARCH (Debian 形式のアーキテクチャ)
DEB_*_ARCH_CPU (Debian CPU 名)
DEB_*_ARCH_OS (Debian システム名)
DEB_*_GNU_TYPE (GNU 形式アーキテクチャ指定文字列)
DEB_*_GNU_CPU (DEB_*_GNU_TYPE の CPU の部分)
DEB_*_GNU_SYSTEM (DEB_*_GNU_TYPE のシステムの部分)

* は BUILD か HOST のどちらかです。 BUILD の場合はパッケージをビルドするアーキテクチャの指定になり、 HOST の場合にはホストアーキテクチャの指定になります。

rules ファイル中で必要な変数に適切な標準値を設定することによって、後方互換性を保つことができます。詳しくは dpkg-architecture のドキュメントを参照して下さい。

DEB_*_ARCH は、ビルドするまたはビルド対象となるマシンの Debian アーキテクチャのみを決定するのだということを理解しておくことは重要です。 CPU やシステムの情報を得るのにこれを使うべきではありません。それには、DEB_*_ARCH_CPU や DEB_*_ARCH_OS 変数を使うべきです。 GNU 書式の変数は、一般的には上流のビルドシステムのみで用いるようにすべきです。

4.9.1 `debian/rules` および `DEB_BUILD_OPTIONS`

標準の環境変数 DEB_BUILD_OPTIONS のサポートを推奨します。この変数は、パッケージをどのようにコンパイル・ビルドするかを変更するための複数のフラグを含みます。各フラグは、flag という形式か、 flag=options という形式でなければいけません。複数のフラグがある場合、空白で分離してください [27]。 flag は英子文字 (a-z) で始まり、英小文字と数字、 - または _ (ハイフンとアンダスコア) のみを含むようにしなければいけません。options には空白を含んではいけません。同一のタグで、矛盾する値を持つものを複数回指定してはいけません。パッケージメンテナは、DEB_BUILD_OPTIONS にはタグ間の矛盾がないことを仮定してもかまいません。

以下のタグの意味は標準化されています。

nocheck: このタグは、パッケージで提供されているビルド時のテスト集を実行しないことを指示します。

noopt: このタグがある場合、このパッケージは最適化を最小限でコンパイルすべきであることを示します。 C プログラムの場合、CFLAGS に -O0 を付ける (これが通常既定値ですが) のが最も良いでしょう。一部のプログラムはこのレベルの最適化だとビルドや実行に失敗するため、その場合には、例えば -O1 を使います。

nostrip: このタグは、パッケージにデバッグ情報を残すため、インストール時にバイナリからデバッグシンボルを strip してはいけないことを意味します。

parallel=n: このタグは、パッケージのビルド時に、ビルドシステムがサポートしている場合 n 多重の並列プロセスで実行すべきであることを示します[28]。パッケージのビルドシステムが並列 make をサポートしていない場合、このオプションは無視されます。また、パッケージビルドシステムが n 未満の並列処理のみをサポートしている場合、パッケージはビルドシステムの許す限りの並列プロセスでビルドされるべきです。パッケージビルド時間が十分に長く、並列ビルドに価値があるほどビルドシステムが安定であるか、の判断はパッケージメンテナに任されています。

未定義のフラグは、debian/rules で無視しなければいけません。

以下の makefile の断片は、どうやってビルドオプション回りを実装するかの例です。この例を自分のパッケージで動作するようにするためには、ひと揉みする必要があるでしょう。

     CFLAGS = -Wall -g
     INSTALL = install
     INSTALL_FILE    = $(INSTALL) -p    -o root -g root  -m  644
     INSTALL_PROGRAM = $(INSTALL) -p    -o root -g root  -m  755
     INSTALL_SCRIPT  = $(INSTALL) -p    -o root -g root  -m  755
     INSTALL_DIR     = $(INSTALL) -p -d -o root -g root  -m  755
     
     ifneq (,$(filter noopt,$(DEB_BUILD_OPTIONS)))
         CFLAGS += -O0
     else
         CFLAGS += -O2
     endif
     ifeq (,$(filter nostrip,$(DEB_BUILD_OPTIONS)))
         INSTALL_PROGRAM += -s
     endif
     ifneq (,$(filter parallel=%,$(DEB_BUILD_OPTIONS)))
         NUMJOBS = $(patsubst parallel=%,%,$(filter parallel=%,$(DEB_BUILD_OPTIONS)))
         MAKEFLAGS += -j$(NUMJOBS)
     endif
     build:
     	# ...
     ifeq (,$(filter nocheck,$(DEB_BUILD_OPTIONS)))
             # パッケージテスト群を実行するためのコード
     endif

4.10 変数置換: `debian/substvars`

dpkg-gencontrol が、バイナリパッケージコントロールファイル (DEBIAN/control) を生成するとき、出力に書きこむ前に変数置換を行ないます。変数置換は ${変数名} の書式を持ちます。オプションであるファイルの debian/substvars 中に使用する変数置換定義を記載します。また、変数置換はソースをパッケージするコマンドに -V オプションを指定することによって、直接 debian/rules から設定することもでき、同時に先行定義されている変数も使用できます。

debian/substvars ファイルは通常 debian/rules ターゲットによって生成され、動的に変更されます。このようなやり方を採った場合には clean ターゲットによって削除しておかなければいけません。

debian/substvars のフォーマットを含んだソースの変数置換の詳細については、 deb-substvars(5) をご覧ください。

4.11 上流のソースの場所の設定 (オプション): `debian/watch`

これは、オプションではありますが推奨の設定ファイルで、新しく提供されたパッケージのアップデートを ftp および http サイトで走査する方法を uscan ユーティリティに対して、伝えるためのものです。これは、http://dehs.alioth.debian.org/ および他の Debian QA ツールで、パッケージ品質管理とディストリビューション全体の保守のために用いられています。

4.12 `debian/files`

このファイルは、ソースツリーの恒常的な部分ではありません。これはパッケージをビルドする途中、どのファイルが生成されたのかを記録するのに用いられます。 dpkg-genchanges は、.changes ファイルを生成するときにこれを用います。

これはアップロードされるソースパッケージに含めるべきではありません。そして、それら (およびすべてのバックアップファイルと一時ファイル、例えば、files.new [29] ) は、clean ターゲットによって削除すべきです。また、 binary ターゲットのスタート時には、これらのファイルを、削除するか空にして新しいスタートを確認することはよいやり方です。

dpkg-gencontrol をバイナリパッケージのため実行した際に、これは dpkg-deb --build をバイナリパッケージ作成のため実行した場合に作成される .deb のためのエントリを debian/files に追加します。このため、たいていのパッケージが、このファイルに関してやらなければいけないことは、clean ターゲットによって削除することだけです。

アップロードするべきファイルが、ソースパッケージと、 dpkg-gencontrol によってコントロールファイルが生成されたバイナリパッケージ以外のファイルを含んでいるときは、それらのファイルはパッケージのトップ階層ディレクトリの親ディレクトリに置かれるべきです。そして、debian/files のリストにファイルを追加するために dpkg-distaddfile を呼ぶようにすべきです。

4.13 コードの便宜的写し

一部のソフトウェアパッケージでは、他のソフトウェアパッケージのコードの写しを含んでおり、ソースからコンパイルする際に複数のパッケージをダウンロードしなくても済むようにしています。 Debian パッケージでは、含まれる側のパッケージが意図的にこのように使われるという想定でないかぎり [30]、このような写しの使い方はすべきではありません。もし、含まれているコードが既に Debian アーカイブでライブラリとして収録されている場合、Debian パッケージングではバイナリパッケージから既にあるライブラリへの参照を行ない、このような写しを使うべきではありません。もし含まれているコードが Debian に収録されていない場合は、可能ならばそのコードを、前提の依存関係を付けて別にパッケージングすべきです [31]。

4.14 ソースパッケージの処理: `debian/README.source`

dpkg-source -x をソースパッケージに対して実行しても、直ぐ編集可能で、変更を加えた後修正されたパッケージを追加作業なしに dpkg-buildpackage で作成できるようなパッケージのソースが得られない場合には、 debian/README.source 解説ファイルの追加を推奨します。このファイルには、以下のすべての手順が説明されていなければいけません。

編集可能で、Debian パッケージの作成が可能な、全部のパッチが当たったソースを作成する方法。これを debian/rules の patch ターゲットで行なえるようにすることが推奨です。debian/rules - メイン構築スクリプト, Section 4.9 参照。

ソースを変更し、その変更をセーブしてパッケージ作成の際に適用できるようにする方法。

パッケージをビルドする際に、現在当てられているソース修正をすべて元に戻す方法。

オプションとして、新しい上流の版がでた場合に (可能なら) Debian ソースパッケージをアップグレードするのに必要な手順の説明。

この説明には具体的なコマンド名や、追加で必要な Debian パッケージについて言及すべきです。また、Debian パッケージングシステムやパッチ管理ツールを熟知していることを仮定してはいけません。

この説明は、ビルド時依存を指定しているパッケージの一つがインストールする文書ファイルを参照してもかまいません。ただし、それは参照された文書が手順を明確に記載しており、一般的なリファレンスマニュアルではない場合に限ります。

debian/README.source には、ソースパッケージを変更しようとする人にとって有益な情報を含めてもかまいません。パッケージが上記の説明に該当するものではなくとも、特に複雑でわかりにくいソース配置やビルドシステム (例えば同じソースを複数回ビルドして異なったバイナリパッケージを作成するようなパッケージ) では、メンテナが debian/README.source を作成することを薦めます。