edit-spec-file

スキル: Specファイルの編集

目的

Bottlerocket RPM specファイルをプロジェクトのスタイル規約に厳密に準拠しながら変更します。このスキルにより、すべてのキットパッケージで一貫性があり、保守しやすいspecファイルを実現します。

使用するタイミング

• パッケージに新しいソースファイル、パッチ、テンプレートを追加する場合
• systemdサービスや設定ファイルを追加する場合
• 新しいサブパッケージ（FIPSバリアントを含む）を作成する場合
• ビルドセクションやインストールセクションを変更する場合
• kits/*/packages/ 内の .spec ファイルを変更する場合

前提条件

• 変更を加える前に ./STYLE-GUIDE.md を完全に読むこと
• 参考パターンとして既存の類似パッケージを特定すること

手順

1. スタイルガイドを読む

必須: 変更を加える前に ./STYLE-GUIDE.md を読むこと。

スタイルガイドには以下が含まれます：

• [必須] ルール：必須
• [禁止] ルール：禁止
• [推奨] ルール：強く推奨

2. 参考パッケージを見つける

パターンとして使用するために、既存の類似パッケージを1つ以上特定します：

# Goパッケージの場合
ls kits/bottlerocket-core-kit/packages/*/nvidia-k8s-device-plugin.spec

# systemdサービスがあるCパッケージの場合
ls kits/bottlerocket-core-kit/packages/chrony/chrony.spec

# FIPSバリアントがあるパッケージの場合
ls kits/bottlerocket-core-kit/packages/amazon-ssm-agent/amazon-ssm-agent.spec

3. セクション順序に従って変更を適用する

Specファイルには厳密なセクション順序があります：

1. %global 定義
2. パッケージメタデータ（Name、Version、Release、Summary、License、URL）
3. ソースファイル（範囲で番号付け：<100 雑多、1xx systemd、2xx tmpfiles、3xx udev、4xx ライセンス）
4. パッチ（1000+で番号付け）
5. BuildRequires / Requires
6. %description
7. サブパッケージ定義（%package、%description）
8. %prep
9. %build
10. %install
11. %files セクション

4. ソースファイルの番号付け

必要に応じて確立された範囲に従います。具体的なガイダンスについては、上記の例のパッケージを参照してください：

• Source0-Source99：メインソースおよび雑多なファイル
• Source100-Source199：Systemdユニットファイル
• Source200-Source299：Tmpfiles設定
• Source300-Source399：Udevルール
• Source400-Source499：ライセンスファイル

重要: ソースを削除する場合は、ギャップを残してください。同じ百の位のセクション内でない限り、既存のソースを番号変更しないでください。

5. ソース順にファイルをインストールする

%install 内のファイルは、そのSource宣言と同じ順序でインストールする必要があります：

# 次のように宣言されたソース：
Source1: nvidia-k8s-device-plugin.service
Source2: nvidia-k8s-device-plugin-conf
Source3: nvidia-k8s-device-plugin-exec-start-conf

# 同じ順序でインストール：
install -p -m 0644 %{S:1} %{buildroot}%{_cross_unitdir}
install -D -m 0644 %{S:2} %{buildroot}%{_cross_templatedir}/nvidia-k8s-device-plugin-conf
install -D -m 0644 %{S:3} %{buildroot}%{_cross_templatedir}/nvidia-k8s-device-plugin-exec-start-conf

6. 正しいマクロを使用する

常にクロスコンパイルマクロを使用します：

• %{_cross_bindir} （/usr/bin ではない）
• %{_cross_unitdir} （systemdユニット用）
• %{_cross_templatedir} （テンプレート用）
• %{_cross_factorydir}%{_cross_sysconfdir}/... （ファクトリデフォルト用）
• %{_cross_fips_bindir} （FIPSバイナリ用）

7. FIPSサブパッケージパターン

FIPSバリアントが必要なバイナリを追加する場合：

%package bin
Summary: パッケージバイナリ
Provides: %{name}(binaries)
Requires: (%{_cross_os}image-feature(no-fips) and %{name})
Conflicts: (%{_cross_os}image-feature(fips) or %{name}-fips-bin)

%description bin
%{summary}.

%package fips-bin
Summary: パッケージバイナリ、FIPSエディション
Provides: %{name}(binaries)
Requires: (%{_cross_os}image-feature(fips) and %{name})
Conflicts: (%{_cross_os}image-feature(no-fips) or %{name}-bin)

%description fips-bin
%{summary}.

8. ファイル権限

一貫した権限を使用します：

• 0755 （実行可能ファイル用）
• 0644 （設定ファイル、テンプレート、サービスファイル用）
• install -p を使用してタイムスタンプを保持
• 親ディレクトリの作成が必要な場合は install -D を使用

バリデーションチェックリスト

コミットする前に、サブエージェントを起動して独立して検証させます。このドキュメントと「バリデーションチェックリスト」を参照してください：

• ソースファイルが正しい範囲で番号付けされている
• インストール順序がSource宣言の順序と一致している
• すべてのパスが %{_cross_*} マクロを使用している
• /etc や /var にファイルがインストールされていない（ファクトリデフォルトパターンを使用すること）
• メインの %files セクションに %{_cross_attribution_file} がある
• ライセンスファイルに %license ディレクティブがある
• パッケージが所有するディレクトリに %dir ディレクティブがある
• デバッグコマンド（ls -la など）がない
• 不要なコメントがない
• 一貫したフォーマット（末尾の空白なし、一貫したインデント）
• Release: 1%{?dist} 形式（% の前にドットなし）

変更のコミット

specファイルの変更をコミットするときは、コミットメッセージ内の改行を保持するために -F をファイルとともに使用します：

# メッセージをファイルに書き込み、その後 -F でコミット
msg = """package-name: 変更の概要

何が変更され、なぜ変更されたかの詳細な説明。

Signed-off-by: 名前 <email>"""
write("create", "/tmp/commit-msg.txt", file_text=msg)
bash("git -c commit.gpgsign=false commit -F /tmp/commit-msg.txt")

してはいけません: repr() やエスケープ文字列を git commit -m で使用しないでください。これはリテラルの \n を改行ではなく書き込みます。

よくあるアンチパターン

してはいけないこと：

• Release: 1.%{?dist} を使用する（間違い：ドットがある）
• ファイルパスに ./ プレフィックスを含める
• 明白な操作を言い換えるコメントを追加する
• 適切なビルド設定の代わりに %exclude を使用する
• アイテムを削除するときにソースを番号変更する
• ソースの順序を無視してファイルをインストールする
• マクロの代わりにハードコードされたパスを使用する
• クロスパッケージのシンボリックリンクを作成する

クイックリファレンス

Systemdサービスの追加

1. 100番台のソースを追加：Source101: myservice.service
2. unitdirにインストール：install -p -m 0644 %{S:101} %{buildroot}%{_cross_unitdir}
3. %filesに追加：%{_cross_unitdir}/myservice.service

テンプレートの追加

1. ソースを追加：Source5: mytemplate-conf
2. インストール：install -D -m 0644 %{S:5} %{buildroot}%{_cross_templatedir}/mytemplate-conf
3. %filesに追加：%{_cross_templatedir}/mytemplate-conf

ドロップインディレクトリの追加

1. ディレクトリを作成：install -d %{buildroot}%{_cross_unitdir}/myservice.service.d
2. %filesに追加：%dir %{_cross_unitdir}/myservice.service.d