# プルリクエストのチェック

プルリクエストを開くと、Hugging Face CI が複数のチェックを実行します。これらのチェックに合格する必要があります。

- [CIの修正](#fixing-the-ci)では、チェックをパスするためにローカルで実行するコマンドが記載されています。
- その後のセクションでは、[コードの品質](#code-quality)や[リポジトリの一貫性](#repository-consistency)など、各チェックが検証する内容について説明しています。
- [テスト](#tests)では、実行されるテスト、テストのカテゴリ、およびスローテストについて説明しています。

## CIの修正

ほとんどの場合、`make style`を実行するだけで、最もよくある失敗原因であるコード品質チェックをクリアできます。

```bash
make style
```

リポジトリの整合性、コピー、または自動生成ファイルに関する問題が発生した場合は、`make fix-repo` を実行してください。これにより、スタイル、コピー、ドキュメント文字列、自動生成ファイルが一度のパスで修正されます。

```bash
make fix-repo
```

より大規模な変更に対しては、以下の3コマンドのシーケンスがすべてのチェックを網羅します。負荷は大きくなりますが、pushする前にすべての問題を検出できます。

```bash
make fix-repo   # auto-fix everything that can be auto-fixed
make typing     # check types and model structure, fix any errors manually
make check-repo # verify all checks pass, fix anything that remains
```

`make typing` は、手動で修正する必要がある型エラーやモデル構造の違反を検出します。`make check-repo` は、最終的な読み取り専用パスを実行して、すべてが準備完了であることを確認できます。

> [!NOTE]
> CI はときどき不安定です。変更内容と無関係な項目でチェックが失敗した場合は、メンテナーに連絡して再実行を依頼してください。

## コードの品質

コード品質チェックは、フォーマット、インポート、型チェック、モデル構造のルールをカバーします。`make fix-repo` および `make typing` に相当します。

`make style`（`make fix-repo` に含まれます）は、[Ruff](https://docs.astral.sh/ruff/) のリンティングとフォーマット、`__init__.py` のインポートの並び順、およびオートマッピングの一貫性を自動修正します。

`make typing` は [ty](https://docs.astral.sh/ty/) を使用して型チェックを実行し、config クラスの命名規則や `forward()` シグネチャを含む TRansFormers (TRF) ルールを検証します。型エラーと TRF の違反は特定のルール番号が報告され、手動での修正が必要です。これらのルールは [mlinter](https://github.com/huggingface/transformers-mlinter) リポジトリに格納されています。すべての TRF ルールを確認するには `python -m utils.mlinter --list-rules` を、特定のルールの完全なドキュメントを表示するには `python -m utils.mlinter --rule TRFXXX` を実行してください。

TRFルールに例外が必要な場合は、以下のオプションのいずれかを選択してください（詳細は[違反の抑制](./modeling_rules#suppressing-violations)を参照）。

- `utils/mlinter/rules.toml` の該当するルールにおいて、`allowlist_models` リストにモデル名を追加してください。モデルファイル全体に例外を適用する場合は、この方法を使用します。
- `# trf-ignore: TRFXXX` を、対象の構文と同じ行、またはその直前の行に追加します。例外を1つの構文にのみ適用する場合に使用します。

## リポジトリの整合性

リポジトリの整合性チェックは`make check-repo`と同様ですが、最初の失敗で停止します。以下のカテゴリ間でリポジトリの内部整合性を保ちます。公開オブジェクトがインポート可能であること、コピーされたコードがソースと同期していること、自動生成ファイル（ダミー、ドキュメントテスト、メタデータ）がコードの現在の状態を反映していることです。新しいモデルについては、すべての新しいモデルクラスが自動マッピングに登録されていることも検証します。

| カテゴリ | 検証対象 | 自動修正されましたか？ |
|---|---|---|
| Init ファイル | `src/transformers/models/` 内の `__init__.py` ファイルは最新の状態です  | `make fix-repo` |
| コピーとモジュール | `# Copied from` ブロックはソースと一致しており、モジュラー生成ファイルは最新の状態です | `make fix-repo` |
| Docstringとドキュメント | 引数のドキュメント文字列は、関数のシグネチャおよびドキュメントの目次と一致しています | `make fix-repo` |
| 自動生成ファイル | ダミー、パイプラインの型付け、doctest リスト、メタデータ、依存関係テーブル | `make fix-repo` |
| 設定の検証 | Config クラスには docstring に有効なチェックポイントが含まれており、config の属性はモデリングファイルと一致しています | マニュアル |
| レビュアーの割り当て | すべてのモデルディレクトリと、レビュアーファイル内のすべてのルールは、依然としてレビュアーに到達します | マニュアル |

## レビュアーの割り当て

`.github/scripts/codeowners_for_review_action` は、どのファイルが誰によってレビューされるかを記録します。

所有権はファイルごとに解決され、より具体的なものから優先的に適用されます。

| どこ | 〜のように見えます | 使用用途 |
|---|---|---|
| モデルファイル | `# Reviewers: @login` を、`modular_<model>.py` または `modeling_<model>.py` の先頭のコメントブロックに記述します。 | そのモダリティのオーナー以外の人を必要とするモデルです。モジュラーコンバーターはヘッダーを生成されたモデリングファイルにコピーするため、タグは再生成後も保持されます。 |
| パスルール | `.github/scripts/codeowners_for_review_action` 内の `/src/transformers/<area>/ @login` | モデル以外のもの |
| モダリティのテーブル | `@@modality/vision @login`、同じファイル内 | `docs/source/en/_toctree.yml` のそのセクションにドキュメントページが配置されているすべてのモデル |
| キャッチオール | `* @Rocketknight1 @ArthurZucker` | 何もない |

新しいモデルにはどこにもエントリを追加する必要はありません。`_toctree.yml` にそのドキュメントページを追加するだけで、これはドキュメントの目次チェックで既に必須とされていることですが、それによりモデルが特定のモダリティに配置され、以降はモダリティのテーブルで自動的にカバーされます。

`make check-repository-consistency` は `utils/check_reviewers.py` を実行します。このスクリプトは、モデルがキャッチオール以外の誰にも割り当てられていない場合、ルールがどのファイルにもマッチしなくなった場合、またはモダリティのテーブルが目次と一致しない場合に失敗します。そのリゾルバーは `transformers` の依存関係ではありません。`utils/checkers-requirements.txt` にリストされており、チェッカーランナーは環境での初回実行時にこれをインストールします。インストールが実行できない場合（オフラインの場合など）、チェックはそれを報告して合格扱いにし、処理をブロックしません。`src/transformers/models` の外側でオーナーが設定されていないパスは、注記として報告されます。リストするには:

```bash
python utils/check_reviewers.py --strict
```

## テスト

CI は、PR で変更された内容に基づいて、対象となるテストのサブセットを実行します。CI は結合したテストを検出するために、[pytest-random-order](https://github.com/jbasko/pytest-random-order) を使用してテストをわずかにランダムな順序で実行します。実行の開始時にランダムシードが出力されるため、`--random-order-seed=<seed>` を使用して同じ順序を再現できます。

テストがローカルの GPU では成功するものの CI では失敗する場合は、`TRANSFORMERS_TEST_DEVICE="cpu"` を設定して、CPU 上で失敗を再現できるか確認してください。

```bash
TRANSFORMERS_TEST_DEVICE="cpu" pytest tests/models/my_model/ -v
```

以下のセクションでは、テストの選択方法、実行されるジョブ、および低速なテストの対処法について説明します。

### テストの選択

CIはすべてのPRで完全なテストスイートを実行しません。CIはすべてのPRで`@slow`デコレータが適用されたテストをスキップし、PRがレビュー対象となった時点で、メンテナーがGPU上でそれらをトリガーします。

`utils/tests_fetcher.py` は、変更されたファイルからインポート依存関係をトレースして影響を受けるテストを特定し、それらのテストのみを実行します。また、共有ユーティリティに変更を加えた際に、他のモデルでのリグレッションも検出します。フェッチャーは、変更されたファイルと影響を受けるテストを出力し、そのリストを `tests_torch_test_list.txt` に書き出します。

fetcherを使用して、CIが実行する内容を正確に再現します。

```bash
python utils/tests_fetcher.py
python -m pytest -n 8 --dist=loadfile -rA -s $(cat test_preparation/tests_torch_test_list.txt)
```

> [!TIP]
> `modeling_utils.py` や `generation/utils.py` といったコアファイルを変更すると、影響を受けるサブセットだけでなく、すべてのモデルテストがトリガーされます。

モデルのすべてのテストを無条件で実行することもできます。直接実行はより高速なローカルでの健全性チェックですが、変更した共有コードによって他のモデルに生じるリグレッションを検出することはできません。

```bash
pytest tests/models/my_model/ -v
```

### テストジョブのカテゴリ

テストは並列CIジョブに分割されており、各ジョブはパスパターンに基づいてファイルを選択します。モデルのPRに関連するジョブは以下の通りです。

- `tests_torch`: モデリングのテスト（`tests/models/*/test_modeling_*.py`）
- `tests_tokenization`: トークナイザのテスト（`tests/models/*/test_tokenization_*.py`）
- `tests_processors`: プロセッサーおよびフィーチャーエクストラクターのテスト（`tests/models/*/test_(processing|image_processing|feature_extractor)_*.py`）
- `tests_generate`: 生成テスト
- `pipelines_torch`: パイプラインのテスト
- `tests_training_ci`: トレーニングループのテスト
- `tests_tensor_parallel_ci`: テンソル並列テスト
- `tests_fsdp_ci`: FSDP テスト

### 低速テスト

通常のCI実行では、`@slow`デコレータが付与されたテストはスキップされます。これらのテストは実際のチェックポイントのダウンロードや、大量の計算リソースを必要とするため、GPUインスタンス上で実行されます。また、PRがレビュー対象となった時点で、メンテナーによってトリガーされます。

Slow tests は NVIDIA A10 で実行され、数値結果は CI ハードウェアとローカルマシンの間でわずかに異なる場合があります。新しいモデルを追加する際、必要に応じてメンテナーは通常、テスト内のこれらの値を調整します。

以下のコマンドで、ローカル環境でスローテストを実行します。

```bash
RUN_SLOW=1 python -m pytest tests/models/my_model/ -v
```

### ドキュメントのビルド

`build_pr_documentation` ジョブはドキュメントをビルドし、プレビューを生成します。ボットがPRにプレビューリンクを投稿し、マージ前にこのチェックがパスする必要があります。失敗の多くは、`toctree` へのエントリが欠けていることが原因です。ローカルでドキュメントをビルドする方法については、docs フォルダー内の [README.md](https://github.com/huggingface/transformers/tree/main/docs) を参照してください。

## `# Copied from` 構文

> [!WARNING]
> 新しいモデルでは、`# Copied from` よりも [モジュラーワークフロー](modular_transformers)（`modular_*.py`）を常に優先してください。`# Copied from` は、可能な限り避けてください。

`# Copied from` メカニズムは、コピーされたコードをソースと同期させます。`make fix-repo` が実行されると、すべての `# Copied from` ブロックがチェックされ、オリジナルに合わせて更新されるため、`# Copied from` ブロック内の編集は上書きされます。代わりにソースを編集し、`make fix-repo` に変更を伝播させましょう。

`# Copied from`の基本的な形式には、次のものがあります。

```py
# Copied from transformers.models.bert.modeling_bert.BertSelfOutput

# Copied from transformers.models.bert.modeling_bert.BertAttention with Bert->Roberta

# Copied from transformers.models.bert.modeling_bert.BertForSequenceClassification with Bert->MobileBert all-casing
```

`with model->newModel` 構文は、コピー後に文字列の置換を適用します。複数の置換はカンマで区切り、左から右の順に適用されます。`all-casing` オプションを使用すると、すべての大文字・小文字のバリアントが一度に置換されます（`Bert`、`bert`、`BERT` がそれぞれ `MobileBert`、`mobilebert`、`MOBILEBERT` に置き換わります）。

