openSUSE:Changes ファイル (RPM) の作成方法
changelog セクション (%changelog)
パッケージに対して変更を行なった場合はいつでも、対応する changelog 項目を作成しなければなりません。これはパッケージの履歴に関する考え方を記述するだけでなく、ユーザやパッケージャ仲間、そして QA (品質保証) に携わる人々に対して、実施した変更内容を説明する意味があります ("osc log" というコマンドもありますが、 SR を受け入れたタイミングで "git merge" のような履歴結合処理を実施しないため、あまり使用されていません) 。
Open Build Service では、パッケージの変更を記録するために個別のファイルが用意されています。このファイルは、 spec ファイルが .spec で終わるのと同様に、 .changes という接尾辞を設定します。 .changes ファイル内の項目は時系列順に並べるものとし、新しい項目が最初に来るように並べます (つまり、ファイルの冒頭に最も新しい項目が表示されるようにします) 。また、公式のリポジトリ (openSUSE:Factory) 内にチェックインした場合は、既存の項目について変更 すべきではありません (それぞれ項目は ---------- で区切られています) 。記述面での問題 (スペルミスなど) の場合は許可される場合もありますし、古い項目の間に新しい項目を追加することが許可される場合もあります。これにより、同時に複数のブランチを用意して、パッケージを並行して開発することができるようになっています。
.changes ファイル内の項目は、たとえば下記のような書式になります:
-------------------------------------------------------------------
Tue Apr 22 20:54:26 UTC 2013 - your@email.com
- level 1 bullet point; long descriptions
should wrap
* level 2 bullet point; long descriptions
should wrap
* another l2 bullet point
- another l1 bullet point
注意: 1 行あたり 67 文字 (項目の区切り "----" と同じサイズ) を目安として改行してください。また、 3 段階以上の箇条書きは定義されていないことにもご注意ください。
2 段階目の箇条書きはアスタリスク "*" で始めるものとしますが、場合によってはプラス記号 "+" で始める場合もあります。 /usr/lib/build/changelog2spec というヘルパースクリプトでは、特にアスタリスク "*" を検出してそれを RPM 内の changelog 内に記録する (`rpm -q --changelog` で表示することができます) 際、適切に 2 段階目の箇条書きとして整形するようになっています。
たとえばバージョン x.y.z へのアップデートの場合、下記のように記述します:
------------------------------------------------------------------- Tue Apr 22 20:54:26 UTC 2013 - your@email.com - Update to version x.y.z: * bling and changes from upstream for that version * just the relevant parts, no info about other OS * and keep it as short as possible - Added new BuildRequires glibc-devel: new dependency - Do magic trick in install section to overcome installation failure - add foobar-fix-ham.patch: <give a reason> - add foobar-remove-spam.patch: <give a reason> - modify foobar-autotools.patch: <give a reason> - remove foobar-libpng15-compat.patch: <give a reason> - ... (other changes done to the package)
一般的な書式
- まずはバージョンの更新があれば、それを優先的に記述します。その際、具体的な更新内容も記載します。
- .spec ファイルへの変更があれば、その内容も説明するものとします。これには 2 つの理由があります:
- 将来のパッケージ変更に備えて、変更点を記録しておくため。さらなる修正が必要な場合はそれを示すことができます (.spec ファイル内にコメントを記載してもかまいません) し、それをいつ追加したのかを残しておくことにもつながります。
- レビュー担当者の作業負担を軽減するため。誤解による拒否を防ぐため、なぜこれを実施したのかを説明することができるためです。
バグ修正と機能の実装
バグを修正した場合や新しい機能を実装した場合、 .changes ファイル内にバグ番号を記載 しなければなりません 。また、修正は提供元の Bugzilla に対しても報告されるべきものであるため、番号の前にプレフィクスを付けて、探しやすくしておいてください。
| プレフィクス | バグ追跡サイト |
|---|---|
| bsc# | bugzilla.suse.com |
| bnc# | bugzilla.novell.com |
| fate# | fate.suse.com |
| bko# | bugzilla.kernel.org |
| kde# | bugs.kde.org |
| bgo# | bugzilla.gnome.org |
| bmo# | bugzilla.mozilla.org |
完全な一覧は 省略表記一覧 にあります。
問題点が CVE 番号などのように外部の識別子であった場合にも、それらを追加する必要があります。このような識別子については、いくつかの書き方があります:
- update to Firefox 13.0 (bnc#765204)
* MFSA 2012-34/CVE-2012-1938/CVE-2012-1937/CVE-2011-3101
Miscellaneous memory safety hazards
- Fix string quoting. [bnc#666416]
- Add xz BuildRequires because we can't build a package for a
xz-compressed tarball without explicitly specifying that... See
bnc#697467 for more details.
- fix bnc#595144 - Compiled binary in ant
パッケージの更新
パッケージを更新した場合、 .changes ファイル内に新しいバージョンに関する説明を追加しなければなりません。これにはアップストリーム (提供元) が開示している changelog のうち、基本的な項目を追加するとよいでしょう。アップストリームが情報を公開していない場合は、 .changes ファイルにバージョン番号の説明のみを記載します。たとえば下記のようになります:
- update to foo 1.2.3: no changelog available
- update to Firefox 13.0.1 * bugfix release
修正の変更
修正内の変更については、必ず パッチのガイドライン に従わなくてはなりません。また、変更点にパッチ名そのものを記載してもよいでしょう:
- fix segfault on load incorrect document (bnc#123456) * foo-1.2.4-buffer-owerflow.patch
- update to Firefox 7 (bnc#720264) * removed obsolete mozilla-cairo-lcd.patch (upstream)