修正案を2つ提示してリードに選んでもらう：Kubeflow Trainerのインストールドキュメントのv2.1.0がv2.3.0になるまで

結果：マージ（2026-10-28 01:03、 kubeflow/trainer#4334）、issue #4310 クローズ、マイルストーンv2.4。 実際にはGitHubのissue、PR、レビュー、タイムライン、チェック履歴、Trainerのソース（PRのベースコミット 8e076764、タグv2.1.0・v2.2.0・v2.3.0のチャートの値）、KubeflowのAIポリシー文書、コントリビューション台帳のドラフトから取得しました。時刻は韓国時間です。

目次

• 一言まとめ
• 1. 何が問題だったのか：エラーなしで無視される値
• 2. なぜPRではなくissueから始めたのか
• 3. 何を変更したのか：diffの要点
• 4. 反応：一晩でのマージ
• 5. 学んだこと：オープンソースへのコントリビューションのコツ
• リンク

一言まとめ

1. 何が問題だったのか：エラーなしで無視される値

TT Labでは卓球スコアボードの認識モデルの学習をKubeflowに移行中で、Kubeflow Trainerはその学習ジョブをKubernetes上で実行するコンポーネントです。 インストールドキュメントを読んでいると、前後の記述が噛み合っていない箇所が見つかりました。行番号はPRのベースコミット 8e076764 を基準としています。

• docs/operator-guides/installation.md 29行目: export VERSION=v2.1.0、そしてHelmインストールは --version ${VERSION#v}.
• 同じページの 59–60行目と 69–71行目：デフォルトランタイムを一緒にインストールするには --set runtimes.defaultEnabled=true、選択してインストールするには --set runtimes.torchDistributed.enabled=true などを付加するように指示されています。
• 48行目：CRDを個別に管理する場合、 --set crds.enabled=false.

チャートの values.yaml をタグごとに開いて確認すると以下のようになります。

Helm 은 값 검증 스키마가 없는 차트에 모르는 키를 넘겨도 오류를 내지 않습니다. 그래서 문서를 그대로 따라 하면 2.1.0 제어부가 깔리고, ClusterTrainingRuntime 은 하나도 생기지 않으며, 왜 그런지 알려 주는 메시지도 없습니다.

細かい枝葉が他に2つありました。kustomizeによるインストールのセクションでは、コントロールプレーンにはバージョンを固定したコマンド（?ref=${VERSION}, 87行目）があるのに、ランタイムには ?ref=master コマンド（96–99行目）しかありませんでした。「リリースバージョンでのインストール」経路を使うと、リリースのCRDとmasterのランタイムが混在することになります。ドキュメントがkubeflow.orgへこのリポジトリのドキュメントサイトから移転する前（#3308）には、両方のコマンドが存在していました。さらに、 docs/user-guides/data-cache.md の51行目 もv2.1.0でした。

何を検証して何を検証しなかったのかを分けて記載します。チャートの値はタグ別のファイルを直接開いて確認し（上の表、2026-10-29に再確認）、チャート2.3.0がOCIレジストリにアップロードされていることと、 manifests/overlays/runtimes·data-cache がv2.3.0に存在することも確認しました。ただし、Helmやkustomizeのコマンドを実際のクラスターで実行してv2.1.0環境でランタイムが作成されない様子を実際に目視確認したわけではありません（未実測）。PRの本文にもその旨を記載しました。

2. なぜPRではなくissueから始めたのか

このリポジトリには、バージョン番号だけを上げようとした要求がクローズされた前例がありました。2026-07-27のissue #3807 「helm install VERSIONをv2.2.1に上げよう」は、同日にリードによって「READMEのバージョンはユーザーがバージョンを選択する方法を示す例示に過ぎない」という理由で閉じられました。

同じ内容をそのままPRとして送ると、同じ理由でクローズされる可能性があります。そのため、ドラフトの段階で3つの事項を決定しました（台帳のドラフトメモ）。

1. PRではなく、まずissueを開きます。
2. 「バージョンが古い」ではなく、「同じページのコマンドがそのバージョンでは密かに無視される」という機能の欠陥を前面に押し出します。#3807に直接言及し、今回は「例示のバージョンが持っていない値に同じページのコマンドが依存している」という点が異なると記述します。
3. バージョンを固定する案だけでなく、例示のバージョンはそのままにしつつ「runtimes.* は2.2.0から、 crds.enabled は2.3.0から」という注記を入れる案も同時に提示します。どちらの案でもPRを送る予定であることを記載します。

issue #4310 は2026-10-26 21:43にこのように作成しました。バグ報告のテンプレートの項目順序に従い、本文の最後に「チャートの値をタグごとに読み取る作業を含め、Claudeが調査とドラフト作成を支援した」というAI使用の旨を記載しました。

2時間45分後にリードから返答がありました。インストールガイドをv2.3にバージョンアップすべきだと述べ、自分で修正してみるかと尋ねられました。同じコメントで /kind docs と /good-first-issue のラベルが付けられました。2つの案のうち最初の案が選ばれた形となりました。

3. 何を変更したのか：diffの要点

リードからの返答をもらった日の午後にPRを開きました。

 # docs/operator-guides/installation.md
-export VERSION=v2.1.0
+export VERSION=v2.3.0
 ...
-Run the following command to deploy Kubeflow Trainer built-in runtimes
+Run the following command to deploy Kubeflow Trainer built-in runtimes:
+
+kubectl apply --server-side -k "https://github.com/kubeflow/trainer.git/manifests/overlays/runtimes?ref=${VERSION}"
+
+For the latest changes run:
 
 kubectl apply --server-side -k "https://github.com/kubeflow/trainer.git/manifests/overlays/runtimes?ref=master"

 # docs/user-guides/data-cache.md
-export VERSION=v2.1.0
+export VERSION=v2.3.0

ランタイムコマンドは、コントロールプレーンのコマンドですでに使われている形式（バージョン固定のコマンド、その下の「最新の変更については」masterコマンド）をそのまま踏襲しました。#3807で閉じられたまさにそのファイルであるチャートのREADMEには手をつけず、本文中でその理由として#3807を参照させました。

PR本文の「どのようにテストしたか」の欄には次のように記述しました。

• ドキュメントのビルドを .readthedocs.yaml と同じ条件（Python 3.12、警告をエラーとして扱う）で python:3.12-slim コンテナ内で実行しました。 make -C docs html SPHINXOPTS="-W --keep-going -q" がmasterと今回の変更の両方で終了コード0、警告なしで完了し、レンダリングされた両方のページに新しいコマンドが表示されていることを確認しました。
• git diff --check はクリーンでした。 .pre-commit-config.yaml にはマークダウンリンターはありません。
• Helm·kustomize 명령 자체는 클러스터에 돌리지 않았습니다.

AIの利用はKubeflowの AIポリシーに従いました。このポリシーでは、AIで作成したコントリビューションはローカルでビルド・テストした上で公開すること、レビューで説明できること、PRの本文やコミットのフッター（Assisted-by·Co-authored-by）で明らかにすること、そしてメンテナーからのフィードバックにAIが自動返答しないことが求められています。コミットに Assisted-by: Claude とDCO署名を付与し、本文には「Claudeがこれを探し、変更のドラフト作成を支援し、上記の確認作業もその支援のもとで実行した」という「AI assistance」の段落を設けました。上記のドキュメントビルドがポリシーの「ローカルでの確認」に該当します。コミットはGitHub上では署名なしコミットとして表示されているようです。

4. 反応：一晩でのマージ

レビューのコメントは「ありがとう」の一言だけでした。issueですでに方向性が決まっていたため、PRで質問すべきことがなかったものとみられます。 ok-to-test のあとに実行されたチェックも含めて13個のチェックがすべて通過し、最も時間がかかった test は58分42秒でした。

issueにはこちらから個別の返信は行いませんでした。台帳には「issueへの返信はユーザーが直接行う」とメモしてありましたが、返信の代わりに翌日のPRで返答した形になりました。KubeflowのAIポリシーの「メンテナーのフィードバックにAIが自動返答しない」という項目とも合致する流れです。

5. 学んだこと：オープンソースへのコントリビューションのコツ

• 「閉じられた前例を事前に探し、その理由に正面から向き合って答えます。」や「READMEのバージョンは例示」というリードの言葉は、バージョン番号に注目する限り正しいものです。今回のissueはその言葉に反論せず、「例示のバージョンが同じページの他のコマンドと噛み合っていない」という別の問題を提示しました。
• 「修正案を2つ提示すると、メンテナーが選びやすくなります。」バージョンを固定するか、注記をつけるかはプロジェクトのドキュメント方針次第です。両方を記載してどちらの案でもPRを送る旨を伝えると、リードは一言で選択して作業を任せてくれました。
• 「「密かに無視される」ということは、表ひとつで示すことができます。」3つのタグの values.yaml において、キーが追加された行番号を示した表により、クラスターで環境を再現しなくても問題を明確に示すことができました。実際に環境で再現しなかったことは「クラスターでは実行していない」と別途書き添えました。
• 「ドキュメントのPRもプロジェクトのビルド条件に従って実行します。」Read the Docsが警告をエラーとして扱う設定になっているため、同じ条件でローカルで事前にビルドしました。AIポリシーが要求する「ローカルでの確認」とは、ドキュメントPRにおいてはこの作業を指すものと捉えました。

T-Labの一言。 料理本の最初の行に「v2.1版のお鍋を取り出してください」と書いてあり、その数行下には「お鍋の蒸しボタンを押してください」と書いてありました。しかし、v2.1版のお鍋には蒸しボタンがありません！ボタンを押す真似をしてもお鍋は何も言わず、夕食に肉まんが蒸し上がることもありません。「お鍋のバージョンを上げるべきか、それとも『蒸しボタンはv2.2版からです』と書き加えるべきでしょうか？」と尋ねたところ、シェフが「バージョンを上げよう、君が直してみるかい？」と言ってくださいました。翌日の朝、修正された料理本が本棚に並びました。

リンク

すべての資料は2026-10-29に閲覧しました。

• issue： kubeflow/trainer#4310
• PR： kubeflow/trainer#4334 （マージコミット 92f88b47)
• 修正したドキュメント（ベースコミット）： installation.md, data-cache.md
• チャートの値： v2.1.0, v2.2.0, v2.3.0
• 前例：issue #3807
• Kubeflow AIポリシー： https://github.com/kubeflow/website/blob/master/content/en/docs/about/ai_policy.md