쿠버네티스 문서 한글화에 기여하기

🥸 사설

개발자라면 누구나 오픈소스 컨트리뷰션에 대한 생각을 해본 적이 있을 것이다. 나 역시 그랬고 오히려 그 이상의 환상을 품고 있었다.
전 세계 개발자들이 사용하는 프로젝트에 나의 흔적을 남긴다는 것, 그리고 그 기여가 누군가에게 도움이 된다는 것 그 상상만으로도 더할 나위 없는 동기부여가 되었다.
 
좀 더 구체적인 예를 들어보자. 나는 Redis, Kafka와 같이 대형 오픈소스 커미터가 되고 싶다는 생각을 꾸준히 해왔다. Kafka는 Apache 재단 산하의 오픈소스로, 이외에도 Apache 재단에는 수많은 프로젝트가 존재한다. 그중에는 Apache Zeppelin처럼 한국인 개발자들이 많이 참여하는 프로젝트도 있다.

만약 내가 지금, 향후 10년 안에 대형 오픈소스로 성장할 만한 프로젝트를 미리 찾아 꾸준히 기여한다면 어떨까?
그 프로젝트가 성공적으로 성장했을 때, 내 이력서에는 이렇게 단 한 줄로 적힐 것이다.
 

“Apache ○○ Committer”

 
단 한 문장만으로 나의 기술력과 경험이 증명되는 것이다.
 
물론, 그 길이 결코 쉽지는 않다.
대형 오픈소스의 커미터가 되기 위해서는 폭넓은 기술 지식과 일정 수준 이상의 개발 역량, 그리고 해당 기술을 깊게 다루는 실무 환경이 필요하기 때문이다.
이에 더해 내가 흥미를 느끼고 꾸준히 사용하는 기술이어야 관심을 유지하며 기여를 지속할 수 있다.
이 모든 조건을 동시에 충족하기란 결코 쉽지 않다.
 
다양한 기술을 실험적으로 도입하고, 그 과정에서 특정 오픈소스를 깊이 다루며 문제를 해결하고, 첫 PR을 머지시킨 뒤 커미터로 성장했다는 이야기의 글을 종종 본 적이 있다. 지금의 나에게 적용하기에는 조금 거리가 있었다.
 
그러던 중, “기술적 기여만이 컨트리뷰션은 아니다”라는 사실을 깨달았다. 코드 외에도 문서, 번역, 디자인, 커뮤니티 운영 등 다양한 방식으로 참여할 수 있다는 것을 알게 된 것이다. 나는 그중에서 대형 오픈소스의 문서 현지화 기여에 관심을 갖게 되었고, 그중에서도 내가 평소 공부해 온 Kubernetes를 선택했다.
 
문서 기여는 개발에 관심 있는 대학생이나 취준생도 참여할 수 있을 정도로 진입 장벽이 낮으면서, 오픈소스의 운영 구조를 직접 경험할 수 있고, 내 기여가 곧바로 문서를 읽는 한국어 사용 개발자들에게 도움이 되는 그야말로 의미와 학습을 동시에 얻을 수 있는 최고의 가성비 컨트리뷰션이라 할 수 있다.(기여 난이도가 낮을 뿐 많은 시간과 노력을 들여야 하는 것은 같다)
 
나는 지난 7월 말부터 쿠버네티스 공식 문서에 본격적으로 기여하기 시작했다. 그 과정에서 열정적이고 뛰어난 분들을 많이 만났고,
회사에서는 쉽게 경험하기 어려운 다양한 인사이트를 얻을 수 있었다. 이제 어느 정도 기여 환경과 프로세스를 이해하게 된 만큼,
과거의 나처럼 “하고는 싶은데, 어떻게 시작해야 할지 모르겠다”는 분들을 위해 가이드를 남기고자 한다.
 

1.  쿠버네티스 공식 문서 살펴보기

https://kubernetes.io/ko/docs/home/

쿠버네티스 문서

쿠버네티스에 관심있는 분들이라면 한 번쯤은 한글화 되어있는 공식 문서를 살펴본 기억이 있을 것이다. CKA를 취득하기 위해 공식 문서를 매일같이 드나들던 때가 있었다. 이때 한글화되어있는 문서를 읽고 나서 "이런 건 도대체 누가 번역하는 걸까?" 하는 생각을 했는데 그 궁금증이 실제 기여까지 이어지게 되었다.
 

쿠버네티스 문서의 경우 HUGO라고 하는 정적 사이트 생성기를 통해 배포된다.
또한, 모든 문서는 Github 저장소(kubernetes/website)에서 마크다운(.md) 파일로 관리되고 있다.
 
 

2.  SIG Docs에 참여하기

쿠버네티스에는 Special Interest Group(SIG)이라고 불리는 여러 그룹이 존재한다. 각 SIG는 특정 분야에 관심 있는 사람들이 모여 해당 영역의 발전을 함께 도모한다. 그중 SIG-Docs는 쿠버네티스 문서를 담당하는 그룹으로, kubernetes Slack 채널을 통해 누구나 쉽게 참여할 수 있다.
특히 한글화 팀은 #kubernetes-docs-ko 채널에서 활동하고 있으며, 이곳에서 대화에 참여하고 기여를 시작함으로써 한글화 팀의 일원이 될 수 있다.
 

3.  CLA 서명하기

CLA(Contributor License Agreement)는 쿠버네티스에 기여하기 위해 반드시 서명해야 하는 문서다.
이는 기여자가 작성한 코드의 권리를 쿠버네티스 커뮤니티에 양도한다는 의미를 담고 있다.
CLA 서명 여부는 풀 리퀘스트(PR)를 생성할 때 자동으로 확인되며, 서명이 완료되지 않은 경우 해당 PR은 머지될 수 없다.
 

CLA 서명을 하지 않고 PR을 작성하는 경우, 봇이 CLA에 서명되지 않았다는 코멘트를 남긴다.
이때 봇이 남긴 링크를 통해 CLA에 서명하면 된다.
자세한 내용은 kubetnetes/community의 CLA.md를 통해 확인할 수 있다.(그대로 따라 하면 된다)
 

첫 PR의 코멘트를 깔끔하게 유지하고 싶다면 다른 저장소를 이용하여 미리 CLA를 등록하는 방법이 있다.
kubernetes-sigs라는 조직에는 contributor-playground라는 저장소가 있다.
이곳은 신규 기여자들이 쿠버네티스 프로젝트의 프로세스에 익숙해지도록 풀 리퀘스트 제출을 연습하는 공간이다.
이곳의 remote 디렉터리 내에 자신의 github 아이디를 이름으로 한 마크다운을 생성하고 풀 리퀘스트를 제출하면 위와 같이 동일하게 CLA 서명이 필요하다는 코멘트가 생성됨으로 동일한 방식으로 서명을 진행하면 된다.
예시를 위해 내가 올린 풀 리퀘스트의 링크를 남긴다.
이 PR이 머지되면 메인테이너로부터 환영 메시지도 받을 수 있으니 추천한다.
 

CLA 서명이 완료 후 풀 리퀘스트를 제출하면 위와 같이 코멘트가 생성된다.
 

4.  현지화(Localization, L10n)에 대해 알아보기

본격적으로 기여하기 전에 용어에 대해 알아보자.
공식 문서 번역의 경우 영어로는 Localization, 한국어로는 현지화라는 용어를 사용한다.
비슷한 말로 국제화(internationalization, i18n)도 있다.
번역 시 가이드 및 규칙은 각 현지화 팀마다 상이하다.
한글화 팀의 경우 쿠버네티스 한글화 가이드를 따르기 때문에 시작 전 내용을 숙지하면 좋다.
이에 더해 한글화 팀에서는 신규 기여자가 기여할 때 자주 하는 실수를 줄이고, 한글화 팀 내부에서 지키고 있는 번역 규칙을 보다 쉽게 설명하기 위해 쿠버네티스 한글화 모범 사례 역시 제공한다.
위 두 링크를 충분히 읽었다면 어렵지 않게 번역을 시작할 수 있을 것이다.
 

5.  기여할 문서 찾기

쿠버네티스 문서 현지화의 경우에는 기본적으로 영어 원문 페이지가 생성되거나 업데이트되면 이를 따라 생성하거나 업데이트하는 방식을 따른다.
따라서 직접 문서 내에 아직 번역이 되지 않은 파일을 찾거나, 사진과 같이 out of date라고 나와 있는 문서를 업데이트하면 된다.
 
kubernetes i18n tracker
최근 Japanese 팀에서 영어 원문과 각 현지화 번역문의 생성 여부 및 업데이트 날짜 차이를 통해 번역이 필요한 문서를 한눈에 볼 수 있는 웹사이트를 자체 개발하여 제공하고 있다.
위 링크를 통해 보다 쉽게 번역할 문서를 찾을 수 있다.
 

6.  기여하기

😎 저장소 포크 후 로컬로 클론 하기

• kubernetes/website 저장소를 포크 하여, 본인 저장소로 가져온다.
• 이를 클론 하여 로컬에 프로젝트를 가져와 번역할 준비를 마친다.

 

✍🏻 번역할 문서 찾고 이슈 등록하기

• 기여할 문서를 찾았다면 제일 중요한 부분이 누군가 이미 작업하고 있지는 않은지 확인하고 이슈를 등록하는 것이다.
• kubernetes/website의 Issues 페이지에서 라벨을 language/ko로 설정하면 한글화 관련 오픈되어 있는 이슈를 확인할 수 있다.
• 여기서 본인이 작업하려고 하는 문서가 이미 다른 기여자에 의해 작업 중인지를 확인한다.
• 이슈를 작성하면 보통 Feature Request이다.
• 제목과 내용은 크게 규칙은 없고, 탬플릿에 맞춰 이슈를 작성하면 된다.
  • 단, 제목에는 [ko]를 붙이고, 언어는 가능한 한 영어로 작성한다.
  • 이는 쿠버네티스 조직 내 저장소에서 지키고 있는 공통 규칙이다.
  • 한국어 외에도 여러 언어가 사용하는 저장소이기 때문이다.
• 또한, 아무리 한글화 관련 풀 리퀘스트라고 할지라도 다른 국적의 메인테이너도 어느 정도 관여를 하기 때문에 기본적으로 영어로 작성해야 한다.
  • 리뷰어와 주고받는 코멘트는 한글로 작성해도 무관하다.

 

🤖 번역 작업과 풀 리퀘스트 생성

번역 파일 위치

• 각 문서는 kubernetes/website 저장소의 /content/(각 언어별 폴더)/(하위 폴더)에 저장되어 있다.
• 아직 번역되지 않은 파일은 /content/en/xxx... 등의 영어 원문과 동일한 경로의 /content/ko/xxx...에 동일한 이름의 마크다운 파일을 생성하고 번역을 진행한다.
• 영어 원문이 업데이트된 경우, /ko 디렉터리 내 동일한 경로의 마크다운 파일을 찾아 업데이트를 진행한다.

 

• 작업 별로 개별 브랜치를 만들어 번역을 진행한다.
• 브랜치 명은 영문으로 간단하면서도 알아보기 쉽게 작성한다.
• 작업이 끝나면 이를 본인의 원격 저장소에 푸시한다.
• 이후 kubernetes/website에서 풀 리퀘스트를 생성한다.
• 머지 방향은 포크 한 본인 저장소 내 작업 브랜치에서 kubernetes/website의 main 저장소이다.
  • 과거에는 릴리즈 별 브랜치를 사용했으나, 현재는 main에 머지하는 방식을 사용한다.
• 이때, 먼저 생성한 이슈를 풀 리퀘스트 내용에 추가해 준다.
  • Closes에 작성하면 해당 풀 리퀘스트가 머지될 시 연결된 이슈도 자동으로 Closed 된다.

 

👀  리뷰어의 리뷰 반영과 최종 머지

• 두 명 이상의 권한이 있는 리뷰어(Member 이상)에게 리뷰를 받고 이를 반영한다.
• 리뷰 반영 이후 어프루버에게 최종 승인(/approve)을 받으면 머지가 되고 컨트리뷰터가 될 수 있다.

 

✨ 쿠버네티스 멤버십 받기

• 쿠버네티스 커뮤니티는 기여 정도에 따라 쿠버네티스 멤버십을 부여한다.
• 처음에는 일반적인 Contributor지만 의미 있는 풀 리퀘스트를 5 건 이상 올리고, 다른 사람의 풀 리퀘스트에도 리뷰를 하는 등 지속적인 기여를 하게 되면 Kubernetes Org Member가 될 수 있으며, 장기간 지속적인 기여 시 Reviewer, Approver 등의 권한을 부여받을 수 있다.
• 자세한 내용은 쿠버네티스 공식 문서 - 역할과 책임에서 확인할 수 있다.