openSUSE:パッケージング修正ガイドライン
目次
修正のライフサイクル
修正は様々な理由からパッケージに加えられるものであり、修正のライフサイクルを適切に設定しておくことが重要です。これにより、修正がなぜ行なわれたのか、いつ削除されたのかを誰も知らないなどといった状況を防ぐことができます。ライフサイクルのステップには、下記のようなものがあります:
- パッケージに修正が追加された
- 修正が変更された (機能面の変更、もしくはベースとなるコードが変わったなど)
- 修正が無効化された (ただし削除前)
- パッケージから修正が削除された
修正のライフサイクルでは、中間のステップは必要に応じて設定されるもので、すべての修正がこの流れ通りになるとは限りません。
ライフサイクルのステップが変わるごとに、 .changes ファイル内で修正の名前とともにその旨を言及する必要があります。これは人間にとって読みやすくする意図だけであり、機械処理される書式では必ずしも必要となるものではありません; 下記は修正の記述例です:
- Add package-awesomeness.patch: Makes package awesome
- Drop package-awesomeness.patch: Upstream made it even more awesome.
- Disable package-awesomeness.patch: Testing if users can live without awesomeness
- Rebase package-awesomeness.patch to apply to the new version.
アップストリーム (提供元) のポリシー
Build Service 側のメンテナンス担当者が、アップストリーム側でも開発者となっていたり、そのグループに属していたりする場合、修正した内容はアップストリームにそのまま送信したほうがよいでしょう。
Build Service 側のパッケージメンテナンス担当者は、 openSUSE 固有の修正でない限り、 Build Service のパッケージ内に単純に修正を追加するのではなく、それを提供元に送って正当性を確認および検証してもらったほうが良いでしょう。このルールは spec ファイル内でも Upstream First (アップストリームを優先する) と呼ばれ、最初の "Patch:" の前にコメントとして記述しておくことをお勧めします。まだ Patch 行がないパッケージの場合は、最後の "Source:" 行の下に記述しておいてください。必要に応じて、その場所に Patch が追加されるようになるためです。
このようなルールにより、メンテナンス担当者の負担を軽減することができます。それは、 Build Service 内だけの修正では文書化や説明、メタデータの設定などが十分とは言い切れず、問題を発生させてしまう場合が多いためです。アップストリームに対しても修正を送信することで、この問題が将来的に解決されることになりますので、双方のメンテナンス担当者が同じ状況下に置かれることになり、古いバージョンに含まれていた潜在的な問題を Build Service に持ち込まずに済むようになります。
"Upstream First" (UF) が期待されるパッケージの例としては、 yast, zypp, SuSEfirewall など、 (open)SUSE がホームグラウンドであるパッケージが挙げられます。 SUSE に直接は関係しないパッケージであっても、 UF を期待するプロジェクトがあることにもご注意ください。
修正のマークアップ ("タグ付け")
自動化ツールの使用を容易にするため、および将来のパッケージ作成者を支援するため、修正は下記のように分類するよう合意しました:
- 修正 (fixes): 通常の修正を意味する用語で、下記 3 種類の分類が行なわれます:
- openSUSE 固有の修正。アップストリームのメンテナンス担当者には関係のないものを指します。
- SLE 固有の修正。アップストリームのメンテナンス担当者には関係がなく、 openSUSE でも必要とならないものを指します。
- アップストリームのソースに対する修正。この場合は、もちろんアップストリームに送信すべきです。
- 機能 (features): パッケージに対して機能を追加するもので、下記 3 種類の分類が行なわれます:
- openSUSE 固有の機能追加 (たとえば AppArmor との統合など) 。アップストリームのメンテナンス担当者には関係のないものを指します。
- SLE 固有の機能追加。アップストリームのメンテナンス担当者には関係がなく、 openSUSE でも必要とならないものを指します。
- アップストリームに提供すべき新しい機能の追加。このような新機能を開発した場合は、必ずアップストリームのメンテナンス担当者と連絡を取り、調整することが重要です。このような仕組みを取ることで、将来的に何も変更することなく、その機能を使い続けることができるようにするためです。機能の開発が終わったら、アップストリームのメンテナンス担当者に受け入れてもらうため、多数の作業が必要となることでしょう。そのため、あらかじめアップストリームのメンテナンス担当者が何を期待しているのか、知っておくとよいでしょう。
タイプ 1: spec ファイル内での 1 行コメント
修正を規約に準拠させるため、 .spec ファイル内で下記のようなコメントを記述する 標準 を策定しました:
# PATCH-FIX-OPENSUSE fix-for-opensuse-specific-things.patch bnc#123456 Patch1: fix-for-opensuse-specific-things.patch # PATCH-FIX-SLE fix-for-sle-specific-things.patch bnc#123456 Patch2: fix-for-sle-specific-things.patch # PATCH-FIX-UPSTREAM fix-for-upstream-sources.patch bnc#123456 Patch3: fix-for-upstream-sources.patch # PATCH-FEATURE-OPENSUSE feature-for-opensuse-specific-things.patch bnc#123456 Patch4: feature-for-opensuse-specific-things.patch # PATCH-FEATURE-SLE feature-for-sle-specific-things.patch bnc#123456 Patch5: feature-for-sle-specific-things.patch # PATCH-FEATURE-UPSTREAM feature-for-upstream.patch bnc#123456 Patch6: feature-for-upstream.patch
特殊な例: 最新のソースコードでは適用に失敗するため、修正そのものを書き換える必要がある場合など、一時的に修正をコメントアウトする必要に迫られる場合があります。このような場合も、修正の定義そのものをコメントアウトするのではなく、適用部分のみをコメントアウトしてください。たとえば再ベースを必要としている場合は、下記のように記述します:
# PATCH-NEEDS-REBASE old-patch.patch bnc#123456 -- Does something old. Was: PATCH-FEATURE-OPENSUSE Patch7: old-patch.patch [...] # %patch7
最後に、電子メールアドレスを追加してください。電子メールアドレスを追加することで、誰が修正を記述したのかを知ることができるため、後から尋ねたい内容ができたような場合に問い合わせを実施できるからです。なお、 " -- " 以降は自由に記述してください。
たとえば下記のようになります:
# PATCH-{FIX|FEATURE}-{OPENSUSE|SLE|UPSTREAM} name-of-file.patch bnc#[0-9]* you@example.com -- this patch makes things totally awesome
また、 Novell またはそれ以外の Bugzilla に対応するバグ報告がある場合は、それも追加してください。これにより、より正確に状況を把握することができます。複数個あるような場合は、それらすべてを記載してください。
一般的には、 Bugzilla の項目が必ず存在しなければならないというわけではありません。リリース済みのパッケージに対して更新を提供するような修正である場合には、 .changes ファイル内に Bugzilla の参照 (BNC#) が必要となります。また、必要に応じて修正の説明も含めておくとよいでしょう。
PATCH-*-UPSTREAM の修正の場合、この修正項目は主に アップストリーム のバグトラッカーへの参照を記述すべきです。このような修正は Upstream First のルールでアップストリームに優先的に送信すべきものであるため、修正内のタグでもその旨を記述してください。これにより修正を追跡することが容易になり、バージョンを更新した際にその修正がまだ必要なものかどうかをすぐに判断できるようになります。もちろん、対応する bnc# バグが既にあれば、そちらも記述してください。
なお、バグ番号を記述する場合は、この記事内にある省略表記をお使いください。ここに記載されていないものであっても、将来的に省略表記が追加される場合があります。
また、修正によっては、どこにも明示的な記録がないものもあります。このような場合は、パッケージ作成者の判断を必要とします。たとえば下記のようなことが考えられます:
- すぐにリリースする必要があるようなものの場合は、バグとして報告してください。これは通常時の要件と同じで、正しく適切なやり方です。
- リリースまでにまだ時間があるようなものの場合で、バグがアップストリーム側で修正済みの場合は、コメントに SVN (またはそれ以外の省略表記) の番号を記載し、次期アップグレードでは修正が不要となる旨を記述してください。
タイプ 2: 修正内での情報提供
ここまでの 標準 には修正で最も重要な項目が抜けています。それは、その修正がなぜ必要なのかと、なぜ最初に配置する必要があるのかです。これらに加えて、修正の状態 (アップストリームにも提供するものか openSUSE 固有のものか、修正なのか機能追加なのかなど) が実際の修正には含まれていません。
openSUSE のカーネルパッケージでは、伝統的に修正そのものにメタデータを直接添付する手法を使用しています。この仕組みにより、アップストリームに修正を送信する場合、たとえ間違って説明を省いてしまったような場合であっても、 Git SCM が取り込むべきメタデータを知ることができるようになります。また逆に、 Git リポジトリから修正を抽出する場合も、ファイルを 1 つ取り出すだけで済む、という利点もあります。
修正ファイルには "キー: 値" の方式で様々な情報を記載するほか、その後ろには説明文を添付します。また、必要であれば diffstat の出力を実際の修正の前に記述します。たとえば下記のようになります:
From: Random J Developer <email@example.org> Date: 2012-07-28 01:28:22 +0200 Subject: input: add Acer Aspire 5710 to nomux blacklist References: bnc#404881 Upstream: submitted Acer Aspire needs to be added to nomux blacklist, otherwise the touchpad misbehaves. --- drivers/input/serio/i8042-x86ia64io.h | 7 +++++++ 1 file changed, 7 insertions(+) --- a/drivers/input/serio/i8042-x86ia64io.h +++ b/drivers/input/serio/i8042-x86ia64io.h @@ -371,6 +371,13 @@ static const struct dmi_system_id __init [...]
なお、 Quilt などのシステムを利用して、説明文を保持しておくことをお勧めします。たとえば `quilt ref --sort --diffstat -p1` のように実行すると、上記のような修正を作成することができます。
情報には下記のようなものがあります:
- From: 修正の元々の作成者を表す電子メールアドレスを指定します。
- Date: 修正を最初に作成した日時を指定します。タイムゾーン付きの ISO-8601 形式のタイムスタンプ形式が推奨されます。新しい修正を作っただけで日付がわからない場合は、その時点で `stat your.patch` を実行して、タイムスタンプを記載してください。
- References: メーリングリストの投稿や Bugzilla 番号などの参照情報を記載します。特に決められた形式はありませんが、ブラウザを利用してアクセスしやすくするため、 URL を利用することをお勧めします。詳しくは #省略表記一覧 をお読みください。
- Upstream: アップストリームでの修正の状況を記述します。特に決められた形式はありませんが、一般的に openSUSE 固有のものである場合は never や no を、まだアップストリーム側での決定がない場合は to be done を、アップストリーム側に送信済みである場合は、 References: にも参照情報を添えて sent や submitted を指定してください。なお、アップストリーム側で動きがない場合は、 dead としてください。
- Subject: 修正に対する 1 行の説明文を英語で記載します。
修正には説明文を記述すべきです。 説明文には、その修正がなぜ必要なのかを記述すべきです。これは他の開発者が修正の必要性を判断する際、その決断に影響するものであるためです。以下の 3 つの質問に対する回答を記載するように心がけるのがよいでしょう: どのコマンドを実行したのか？, コマンドを実行した結果、どのようになったのか？, その結果はどうあるべきだったのか？ 。また、たとえばソースファイル内の文法エラーを修正するような場合、コンパイラが出力するものなど、関連するエラーメッセージのうち主要な箇所を記載しておくべきです。これに加えて、修正全体を読まなければわからないような、解決の実装方法についての概要なども、記しておく必要があります。
このようなタグを設定する必要性について、詳しくはメーリングリストの投稿 (いずれも英語) をお読みください: (1) (2) (3)
修正の命名
すべての新しい修正には、 '.patch' の拡張子を付与すべきです。
また、修正の名前は対象となるパッケージの名前で始まるべきで、残りの名前は必要に応じて設定します。どのような名前にしたらよいのかお悩みの場合は、パッケージ内に既にある修正を参考にしてください。
なお、 Patch: 行では %{version} マクロを使用しては なりません 。バージョン番号はそのまま記述すべきです。マクロを使用してしまうと、下記のような問題が発生します:
- バージョンが新しくなった場合、修正のファイル名も変更する必要が生じてしまう。
- 不要な修正を判断するのが難しくなってしまう。
- 最後に修正を変更したのがどのタイミングだったのか、わからなくなってしまう。
- 修正がどのバージョンまで有効だったのかがわからなくなってしまう。
なお、これにも例外があります。コンパイラが誤ったコードに対して出力する警告を修正する場合、よく abuild.patch のような命名をします。
パッチレベルを記述したい場合、 -p1 のような形式がお勧めです。これにより、 quilt などをより直接的に利用して取り込むことができるようになります。
省略表記一覧
混乱や不要な手間を省くため、 Bugzilla の参照を記述する際は、省略表記をお使いください。下記にはよく用いられる Bugzilla とその省略表記を示しています。この省略表記に続いて "#" を書き、番号を続けてください。なお、省略表記と "#" 、および番号の間にはスペースを入れないでください。