고칠 방법 둘을 내밀고 리드가 고르게 하기: Kubeflow Trainer 설치 문서의 v2.1.0 이 v2.3.0 이 되기까지

결과: 병합 (2026-10-28 01:03, kubeflow/trainer#4334), 이슈 #4310 닫힘, 마일스톤 v2.4. 사실은 GitHub 의 이슈·PR·리뷰·타임라인·검사 기록, Trainer 소스(PR 의 바탕 커밋 8e076764, 태그 v2.1.0·v2.2.0·v2.3.0 의 차트 값), Kubeflow 의 AI 정책 문서, 기여 원장의 초안에서 가져왔습니다. 시각은 한국 시간입니다.

목차

• 한 줄 요약
• 1. 무엇이 문제였나: 오류 없이 무시되는 값
• 2. 왜 PR 이 아니라 이슈부터였나
• 3. 무엇을 바꿨나: diff 요지
• 4. 반응: 하룻밤 사이의 병합
• 5. 배운 것: 오픈소스 기여 요령
• 링크

한 줄 요약

1. 무엇이 문제였나: 오류 없이 무시되는 값

TT Lab 은 탁구 점수판의 인식 모델 학습을 Kubeflow 로 옮기는 중이고, Kubeflow Trainer 는 그 학습 작업을 쿠버네티스에서 돌리는 구성 요소입니다. 설치 문서를 읽다가 위아래가 맞지 않는 것을 봤습니다. 줄 번호는 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 은 하나도 생기지 않으며, 왜 그런지 알려 주는 메시지도 없습니다.

곁가지가 둘 더 있었습니다. 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 명령을 실제 클러스터에 돌려 2.1.0 에서 런타임이 안 생기는 모습을 보지는 않았습니다(미실측). PR 본문에도 그렇게 적었습니다.

2. 왜 PR 이 아니라 이슈부터였나

이 저장소에는 판 번호만 올리자던 요청이 닫힌 선례가 있었습니다. 2026-07-27 의 이슈 #3807 「helm install VERSION 을 v2.2.1 로 올리자」 는 같은 날 리드가 「README 의 판은 사용자가 판을 고르는 방법을 보여 주는 예시일 뿐」이라며 닫았습니다.

같은 내용을 PR 로 바로 보내면 같은 이유로 닫힐 수 있습니다. 그래서 초안 단계에서 세 가지를 정했습니다(원장의 초안 메모).

1. PR 대신 이슈를 먼저 엽니다.
2. 「판이 낡았다」가 아니라 「같은 페이지의 명령이 그 판에서는 조용히 무시된다」는 기능 결함을 앞에 둡니다. #3807 을 직접 언급하고, 이번 것은 「예시 판이 갖지 않은 값에 같은 페이지의 명령이 기대고 있다」는 점이 다르다고 적습니다.
3. 판을 고정하는 안만 내밀지 않고, 예시 판을 두되 「runtimes.* 는 2.2.0 부터, crds.enabled 는 2.3.0 부터」라는 주석을 다는 안도 함께 내밉니다. 어느 쪽이든 PR 을 보내겠다고 적습니다.

이슈 #4310 은 2026-10-26 21:43 에 이 모양으로 열었습니다. 버그 보고 양식의 칸 순서를 따랐고, 본문 끝에 「차트 값을 태그마다 읽는 일을 포함해 Claude 가 조사와 초안을 도왔다」는 AI 고지를 넣었습니다.

2시간 45분 뒤 리드가 답했습니다. 설치 가이드를 v2.3 으로 올려야 한다며, 직접 고쳐 보겠느냐고 물었습니다. 같은 댓글로 /kind docs 와 /good-first-issue 라벨을 붙였습니다. 두 안 중 첫째를 고른 셈입니다.

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. 반응: 하룻밤 사이의 병합

리뷰 댓글은 감사 한마디뿐이었습니다. 이슈에서 이미 방향을 정했으니 PR 에서 물을 것이 없었던 것으로 보입니다. ok-to-test 뒤에 돈 검사까지 13개가 모두 통과했고, 가장 긴 test 는 58분 42초였습니다.

이슈에 우리가 따로 답글을 달지는 않았습니다. 원장에는 「이슈 답글은 사용자가 직접」이라고 적어 두었는데, 답글 대신 다음 날 PR 로 답한 셈이 되었습니다. Kubeflow AI 정책의 「메인테이너 피드백에 AI 가 자동으로 답하지 않는다」는 항목과도 맞는 흐름입니다.

5. 배운 것: 오픈소스 기여 요령

• 「닫힌 선례를 먼저 찾고, 그 이유에 정면으로 답합니다.」 「README 의 판은 예시」라는 리드의 말은 판 번호만 보면 옳습니다. 이번 이슈는 그 말을 반박하지 않고, 「예시 판이 같은 페이지의 다른 명령과 맞지 않는다」는 다른 문제를 보였습니다.
• 「고칠 방법을 둘 내밀면 메인테이너가 고르기 쉽습니다.」 판을 고정할지, 주석을 달지는 프로젝트의 문서 방침에 달린 일입니다. 둘 다 적고 어느 쪽이든 PR 을 보내겠다고 하자, 리드는 한 줄로 고르고 일을 넘겨주었습니다.
• 「「조용히 무시된다」는 표 하나로 보입니다.」 태그 셋의 values.yaml 에서 키가 생긴 행 번호를 적은 표가, 클러스터에서 재현하지 않고도 문제를 보여 주었습니다. 재현하지 않은 것은 「클러스터에서는 돌리지 않았다」고 따로 적었습니다.
• 「문서 PR 도 프로젝트의 빌드 조건으로 돌립니다.」 Read the Docs 가 경고를 실패로 다루는 설정이라, 같은 조건으로 로컬에서 먼저 빌드했습니다. AI 정책이 요구하는 「로컬 확인」 이 무엇인지 문서 PR 에서는 이것으로 보았습니다.

티티 한마디. 요리책 첫 줄에 「2.1 판 냄비를 꺼내세요」라고 쓰여 있고, 몇 줄 아래에 「냄비의 찜 단추를 누르세요」라고 쓰여 있었어요. 그런데 2.1 판 냄비에는 찜 단추가 없어요! 누르는 시늉을 해도 냄비는 아무 말이 없고, 저녁에는 찐 만두가 없죠. 「냄비 판을 올릴까요, 아니면 '찜 단추는 2.2 판부터' 라고 적을까요?」 하고 여쭸더니 주방장님이 「판을 올리자, 네가 고쳐 볼래?」 하셨어요. 다음 날 아침에 고친 요리책이 책장에 꽂혔어요.

링크

모든 자료는 2026-10-29 에 열람했습니다.

• 이슈: kubeflow/trainer#4310
• PR: kubeflow/trainer#4334 (병합 커밋 92f88b47)
• 고친 문서(바탕 커밋): installation.md, data-cache.md
• 차트 값: v2.1.0, v2.2.0, v2.3.0
• 선례: 이슈 #3807
• Kubeflow AI 정책: https://github.com/kubeflow/website/blob/master/content/en/docs/about/ai_policy.md