상태: 초안 (2026-10-17), 저장소 문서 + 파일 실측. 기준은 KubeVirt v1.9.0(커밋 79d34c17)의 CONTRIBUTING.md, docs/reviewer-guide.md, docs/getting-started.md, OWNERS 파일, PR 템플릿입니다. 시험과 빌드는 돌리지 않았습니다.

KubeVirt 소스 코드 읽기 8: 기여 입문

목차

• 1. 직관: 사람의 판단과 봇의 라벨
• 2. 그림
• 3. OWNERS 로 지도 다시 보기
• 4. 명령과 라벨
• 5. 리뷰 안내서가 보라는 것
• 6. 첫 기여로 좋은 자리
• 7. 시험 돌리는 법과 필요한 도구
• 8. 한계
• 참고

1. 직관: 사람의 판단과 봇의 라벨

KubeVirt 의 PR 은 사람 둘의 판단이 있어야 병합됩니다. reviewer 가 「코드가 좋다」(/lgtm), approver 가 「이 저장소에 들여도 된다」 (/approve)고 말합니다. 누가 reviewer·approver 인지는 PR 이 건드린 폴더의 OWNERS 파일이 정하고, 말은 PR 댓글의 슬래시 명령으로 합니다. 그 말을 라벨로 바꾸고, 시험 레인을 돌리고, 조건이 다 맞으면 병합하는 것은 prow 라는 봇 묶음입니다. 쿠버네티스와 같은 방식이라 한쪽에서 익히면 다른 쪽에서도 씁니다.

2. 그림

3. OWNERS 로 지도 다시 보기

v1.9.0 에는 OWNERS 파일이 141개 있습니다(실측). 루트 OWNERS 는 모든 파일의 기본 reviewer·approver 를 별칭 code-reviewers·approvers 로 정하고, 빌드 파일(BUILD.bazel, Makefile 등)은 sig-buildsystem 으로 따로 돌립니다. 폴더의 OWNERS 는 더 좁힙니다. 예를 들어 3편의 pkg/virt-controller/watch/vm/OWNERS 는 이렇습니다.

reviewers:
  - sig-compute-reviewers
approvers:
  - sig-compute-approvers
labels:
  - area/controller
  - sig/compute

출처: kubevirt/kubevirt v1.9.0 pkg/virt-controller/watch/vm/OWNERS(주석 줄 제외, Apache-2.0). 이 폴더를 건드린 PR 에는 prow 가 sig/compute·area/controller 라벨을 붙이고 sig-compute 에서 리뷰어를 고릅니다. 별칭의 실제 이름은 OWNERS_ALIASES 에 있습니다. 인원을 세 보면 이렇습니다(v1.9.0, 실측).

이 표가 곧 코드 지도의 다른 얼굴입니다. 4·5편의 네트워크 코드(pkg/network, converter/network)는 sig-network, 6편의 스토리지 쪽 (pkg/storage)은 sig-storage, 나머지 대부분은 sig-compute 가 봅니다. 리뷰를 빨리 받고 싶으면 PR 을 한 SIG 의 폴더 안에 머물게 하는 것이 좋습니다. 여러 SIG 를 건드리면 approver 도 여럿이 필요합니다.

4. 명령과 라벨

병합은 사람이 버튼을 누르지 않고 tide 가 합니다. 두 라벨과 시험 통과가 갖춰지고 막는 라벨(do-not-merge/…, /hold)이 없으면 큐에 넣습니다. 초안(draft) PR 은 CI 를 돌리지 않고 리뷰어도 배정되지 않으니, 방향을 묻고 싶을 때는 초안으로 여는 것이 예의입니다.

PR 에 꼭 있어야 하는 것은 셋입니다.

1. 모든 커밋의 Signed-off-by: — DCO. git commit -s 로 붙입니다. 없으면 DCO 검사가 막습니다.
2. PR 템플릿의 release-note 블록 — 사용자에게 보일 변화면 한 줄, 아니면 NONE. 릴리스 노트가 이 블록에서 만들어집니다.
3. 시험 — 리뷰 안내서의 최저선은 「새 코드에는 단위 시험, 새 기능과 버그 수정에는 e2e 시험 하나 이상」 입니다 (reviewer-guide.md:103 부근).

커밋 메시지는 쿠버네티스 규칙을 따릅니다(docs/commit-message-guidelines.md). 제목 50자 안팎·명령형·마침표 없음, 본문은 72자에서 줄바꿈, 본문에 무엇과 왜를 적고 Fixes #123 같은 키워드는 커밋이 아니라 PR 설명에 씁니다. 앞에 net, vmi: 같은 영역 접두사를 붙이는 예가 문서에 있습니다. 그리고 v1.9.0 의 PR 템플릿 체크리스트에는 KubeVirt AI 기여 정책을 지켰는지 묻는 항목이 있습니다. 도구의 도움을 받아 쓴 PR 이면 그 정책을 먼저 읽으세요.

5. 리뷰 안내서가 보라는 것

docs/reviewer-guide.md 는 짧지만, 앞의 일곱 편에서 본 설계가 왜 그런지를 거꾸로 설명해 줍니다. 리뷰를 받을 때 나올 말을 미리 알 수 있습니다.

• 노드 구성요소에 인포머를 더하지 마라(:43). 4편에서 virt-handler 가 VMI 를 노드 라벨로 걸러 보는 이유입니다. 반대로 virt-api 에서는 인포머 대신 GET 을 쓰라고 합니다. virt-api 는 자유롭게 늘어나는 구성요소라 캐시를 들면 객체 전송이 폭증하기 때문입니다.
• 만들지 않은 객체는 PATCH, 만든 객체는 UPDATE. 2편의 서브리소스가 VM 을 JSON 패치로 고치는 이유입니다. status 를 여럿이 나눠 쓰면 필드를 좁힌 PATCH 를 쓰라고 합니다(3·4편의 VMI status).
• 이벤트는 상태가 바뀔 때 한 번만. reconcile 마다 이벤트를 쏘면 API 서버가 붐빕니다.
• 목록의 순서를 지켜라. 두 컨트롤러가 같은 조건 목록을 서로 다른 순서로 쓰면 「갱신 폭풍」 이 생긴다는 예가 바로 virt-controller 와 virt-handler 의 VMI 조건입니다.
• 특권이 필요한 노드 작업은 virt-launcher 가 아니라 virt-handler 에. 4·5편의 분업 그대로입니다.
• 업그레이드 길을 생각하라. 새 virt-handler 가 옛 virt-launcher 와 말이 통해야 합니다(4편의 proto).
• 코딩 스타일은 goimports·shfmt, Go 의 흔한 실수는 Bazel 의 nogo 분석기들이 빌드에서 걸러 냅니다.

6. 첫 기여로 좋은 자리

이 시리즈의 지도에서 보면, 처음에는 한 파일과 그 시험만 건드리는 자리가 좋습니다.

• 라벨로 고르기. good-first-issue·help-wanted·kind/bug 라벨(CONTRIBUTING.md 49행의 안내).
• 문서와 코드의 어긋남. 이 시리즈를 쓰며 하나를 실제로 보았습니다. docs/components.md 는 파드 안 libvirt 데몬을 libvirtd 라고 설명하지만 v1.9.0 은 virtqemud 를 띄웁니다(1·5편). 문서 PR 은 시험 부담이 적고, 고치는 과정에서 코드를 정확히 읽게 됩니다. CDI 쪽에서 크기 계산을 문서에 더하는 PR(#4318)도 같은 종류입니다(6편).
• converter 의 설정기 하나. pkg/virt-launcher/virtwrap/converter/compute/ 의 파일은 장치 하나씩이고 옆에 _test.go 가 있습니다(5편). 가짜 클러스터 없이 VMI → 도메인 구조체만 보는 단위 시험이라 돌리기도 쉽습니다.
• 웹훅의 검증과 메시지. admitters/ 의 함수는 입력(스펙)과 출력(StatusCause 목록)이 분명합니다(2편). 오류 메시지의 필드 경로나 문구를 다듬는 일도 리뷰 안내서가 보라는 「합리적인 오류 메시지」 입니다.
• 로그와 이벤트. 로그의 pos 로 코드를 찾는 법(1편)을 쓰면, 같은 줄이 너무 자주 찍히는 곳(7편의 장치 검사 로그처럼)을 실제 클러스터에서 발견할 수 있습니다. 고치기 전에 이슈로 먼저 물어보는 편이 좋습니다.

7. 시험 돌리는 법과 필요한 도구

이번 글을 쓰며 시험은 돌리지 않았고, 아래 도구도 받지 않았습니다. 필요한 것만 적습니다.

단위 시험. 가장 확실한 길은 저장소가 정한 빌더 컨테이너입니다.

make test                                    # Bazel 로 전체(빌더 컨테이너 안)
make go-test WHAT=./pkg/virt-controller/...  # Bazel 없이 go test (역시 컨테이너 안)

필요한 것은 Docker 또는 Podman, rsync, 그리고 처음 한 번 받는 빌더 이미지(quay.io/kubevirt/builder:<판>, hack/dockerized 19행)입니다. 컨테이너 밖에서 go test 를 바로 돌리려면 go.mod 의 go 1.26.0 에 맞는 Go 와, virt-launcher 쪽 패키지가 cgo 로 쓰는 libvirt 개발 헤더 (libvirt.org/go/libvirt)가 필요합니다. 컨테이너 밖에서 어느 패키지까지 도는지는 import 를 따라가 봐야 해서 이번에는 확인하지 않았습니다 (미확인). 처음에는 컨테이너가 편합니다. 단위 시험도 Ginkgo 라서 하나만 돌릴 때는 -ginkgo.focus='문자열' 을 넘깁니다.

기능 시험. make cluster-up 이 kubevirtci 로 노드를 VM 으로 띄운 클러스터를 만들고, make cluster-sync 가 내 빌드를 올리고, make functest 가 tests/ 를 돌립니다. 일부만 돌릴 때는 FUNC_TEST_ARGS='--focus-file=…' 를 씁니다(docs/getting-started.md 221행). 필요한 것은 중첩 가상화가 되는 리눅스 기계(맥에서는 어렵습니다), 넉넉한 메모리, 그리고 kubevirtci 가 받는 노드 이미지입니다. PR 에서는 이 시험을 prow 레인이 SIG 별로 대신 돌려 주므로, 처음에는 단위 시험까지만 내 기계에서 돌리고 기능 시험은 레인 결과를 읽는 것으로 시작해도 됩니다.

8. 한계

• prow 레인의 이름과 개수, tide 의 정확한 병합 조건은 kubevirt/project-infra 저장소에 있고 이번에 열지 않았습니다(미확인).
• 별칭 인원은 v1.9.0 시점의 파일입니다. main 에서는 달라질 수 있습니다.
• 빌드·시험 시간은 미실측입니다.

티티 한마디. 첫 PR 은 작을수록 좋아요. 파일 하나, 시험 하나, 왜 바꿨는지 한 문단! 그리고 리뷰 댓글은 공격이 아니라 지도의 빈칸을 채워 주는 거예요. 고맙다고 하고 하나씩 고치면 돼요!

참고

모두 2026-10-17 에 열람했습니다.

• CONTRIBUTING.md: https://github.com/kubevirt/kubevirt/blob/v1.9.0/CONTRIBUTING.md
• 리뷰 안내서: https://github.com/kubevirt/kubevirt/blob/v1.9.0/docs/reviewer-guide.md
• 커밋 메시지 규칙: https://github.com/kubevirt/kubevirt/blob/v1.9.0/docs/commit-message-guidelines.md
• PR 템플릿: https://github.com/kubevirt/kubevirt/blob/v1.9.0/.github/PULL_REQUEST_TEMPLATE.md
• prow 명령 목록: https://prow.ci.kubevirt.io/command-help
• KubeVirt AI 기여 정책: https://github.com/kubevirt/community/blob/main/ai-contribution-policy.md
• 개발 안내(시험): https://github.com/kubevirt/kubevirt/blob/v1.9.0/docs/getting-started.md