SIG Docs에 참여하기

SIG Docs는 쿠버네티스 프로젝트의 분과회(special interest group) 중 하나로, 쿠버네티스 전반에 대한 문서를 작성하고, 업데이트하며 유지보수하는 일을 주로 수행한다. 분과회에 대한 보다 자세한 정보는 커뮤니티 GitHub 저장소 내 SIG Docs 를 참조한다.

SIG Docs는 모든 컨트리뷰터의 콘텐츠와 리뷰를 환영한다. 누구나 풀 리퀘스트(PR)를 요청할 수 있고, 누구나 콘텐츠에 대해 이슈를 등록하거나 진행 중인 풀 리퀘스트에 코멘트를 등록할 수 있다.

멤버, 리뷰어, 또는 승인자가 될 수 있다. 이런 역할은 변경을 승인하고 커밋할 수 있도록 보다 많은 접근 권한과 이에 상응하는 책임이 수반된다. 쿠버네티스 커뮤니티 내에서 멤버십이 운영되는 방식에 대한 보다 많은 정보를 확인하려면 커뮤니티 멤버십 문서를 확인한다.

문서의 나머지에서는 대외적으로 쿠버네티스를 가장 잘 드러내는 수단 중 하나인 쿠버네티스 웹사이트와 문서를 관리하는 책임을 가지는 SIG Docs에서, 이런 체계가 작동하는 특유의 방식에 대한 윤곽을 잡아보겠다.

SIG Docs 의장

SIG Docs를 포함한 각 SIG는, 한 명 이상의 SIG 멤버가 의장 역할을 하도록 선정한다. 이들은 SIG Docs와 다른 쿠버네티스 조직 간 연락책(point of contact)이 된다. 이들은 쿠버네티스 프로젝트 전반의 조직과 그 안에서 SIG Docs가 어떻게 운영되는지에 대한 폭넓은 지식을 갖추어야한다. 현재 의장의 목록을 확인하려면 리더십 문서를 참조한다.

SIG Docs 팀과 자동화

SIG Docs의 자동화는 다음의 두 가지 메커니즘에 의존한다. GitHub 팀과 OWNERS 파일이다.

GitHub 팀

GitHub의 SIG Docs 팀에는 두 분류가 있다.

그룹의 전원과 의사소통하기 위해서 각각 GitHub 코멘트에서 그룹의 @name으로 참조할 수 있다.

가끔은 Prow와 GitHub 팀은 정확히 일치하지 않고 중복된다. 이슈, 풀 리퀘스트를 할당하고, PR 승인을 지원하기 위해서 자동화 시스템이 OWNERS 파일의 정보를 활용한다.

OWNERS 파일과 전문(front-matter)

쿠버네티스 프로젝트는 GitHub 이슈와 풀 리퀘스트 자동화와 관련해서 prow라고 부르는 자동화 툴을 사용한다. 쿠버네티스 웹사이트 리포지터리는 다음의 두개의 prow 플러그인을 사용한다.

이 두 플러그인은 kubernetes/website GitHub 리포지터리 최상위 수준에 있는 OWNERS와 OWNERS_ALIASES 파일을 사용해서 해당 리포지터리에 대해 prow가 작동하는 방식을 제어한다.

OWNERS 파일은 SIG Docs 리뷰어와 승인자의 목록을 포함한다. OWNERS 파일은 하위 디렉터리에 있을 수 있고, 해당 하위 디렉터리와 그 이하의 파일에 대해 리뷰어와 승인자 역할을 수행할 사람을 새로 지정할 수 있다. 일반적인 OWNERS 파일에 대한 보다 많은 정보는 OWNERS 문서를 참고한다.

추가로, 개별 마크다운(Markdown) 파일 내 전문에 리뷰어와 승인자를 개별 GitHub 사용자 이름이나 GitHub 그룹으로 열거할 수 있다.

OWNERS 파일과 마크다운 파일 내 전문의 조합은 자동화 시스템이 누구에게 기술적, 편집적 리뷰를 요청해야 할지를 PR 소유자에게 조언하는데 활용된다.

병합 작업 방식

풀 리퀘스트 요청이 콘텐츠를 발행하는데 사용하는 브랜치에 병합되면, 해당 콘텐츠는 https://kubernetes.io 에 공개된다. 게시된 콘텐츠의 품질을 높히기 위해 SIG Docs 승인자가 풀 리퀘스트를 병합하는 것을 제한한다. 작동 방식은 다음과 같다.

다음 내용

쿠버네티스 문서화에 기여하는 일에 대한 보다 많은 정보는 다음 문서를 참고한다.

1 - 역할과 책임

누구나 쿠버네티스에 기여할 수 있다. SIG Docs에 대한 기여가 커짐에 따라, 커뮤니티의 다양한 멤버십을 신청할 수 있다. 이러한 역할을 통해 커뮤니티 내에서 더 많은 책임을 질 수 있다. 각 역할마다 많은 시간과 노력이 필요하다. 역할은 다음과 같다.

모든 사람

GitHub 계정을 가진 누구나 쿠버네티스에 기여할 수 있다. SIG Docs는 모든 새로운 기여자를 환영한다!

모든 사람은 다음의 작업을 할 수 있다.

CLA에 서명 후에 누구나 다음을 할 수 있다.

자세한 내용은 새로운 콘텐츠 기여하기를 참고한다.

멤버

멤버는 kubernetes/website 에 여러 개의 풀 리퀘스트를 제출한 사람이다. 멤버는 쿠버네티스 GitHub 조직의 회원이다.

멤버는 다음의 작업을 할 수 있다.

멤버 되기

최소 5개의 실질적인 풀 리퀘스트를 제출하고 다른 요구 사항을 충족시킨 후, 다음의 단계를 따른다.

  1. 멤버십을 후원해줄 두 명의 리뷰어 또는 승인자를 찾는다.

    슬랙의 #sig-docs 채널 또는 SIG Docs 메일링 리스트에서 후원을 요청한다.

    참고:

    SIG Docs 멤버 개인에게 직접 email을 보내거나 슬랙 다이렉트 메시지를 보내지 않는다. 반드시 지원서를 제출하기 전에 후원을 요청해야 한다.

  2. kubernetes/org 리포지터리에 GitHub 이슈를 등록한다. Organization Membership Request 이슈 템플릿을 사용한다.

  3. 후원자에게 GitHub 이슈를 알린다. 다음 중 하나를 수행할 수 있다.

  4. 여러분의 이메일 계정으로 수신된 쿠버네티스 GitHub 조직으로의 초대를 수락한다.

    참고:

    GitHub은 초대를 여러분 계정의 기본 이메일 주소로 보낸다.

리뷰어

리뷰어는 열린 풀 리퀘스트를 리뷰할 책임이 있다. 멤버 피드백과는 달리, PR 작성자는 리뷰어의 피드백을 반드시 해결해야 한다. 리뷰어는 @kubernetes/sig-docs-{language}-reviews GitHub 팀의 멤버이다.

리뷰어는 다음의 작업을 수행할 수 있다.

여러분은 SIG DOcs 리뷰어이거나, 특정 주제 영역의 문서에 대한 리뷰어일 수 있다.

풀 리퀘스트에 대한 리뷰어 할당

자동화 시스템은 모든 풀 리퀘스트에 대해 리뷰어를 할당한다. /assign [@_github_handle] 코멘트를 남겨 특정 사람에게 리뷰를 요청할 수 있다.

지정된 리뷰어가 PR에 코멘트를 남기지 않는다면, 다른 리뷰어가 개입할 수 있다. 필요에 따라 기술 리뷰어를 지정할 수도 있다.

/lgtm 사용하기

LGTM은 "Looks good to me"의 약자이며 풀 리퀘스트가 기술적으로 정확하고 병합할 준비가 되었음을 나타낸다. 모든 PR은 리뷰어의 /lgtm 코멘트가 필요하고 병합을 위해 승인자의 /approve 코멘트가 필요하다.

리뷰어의 /lgtm 코멘트는 구속력 있고 자동화 시스템이 lgtm 레이블을 추가하도록 트리거한다.

리뷰어 되기

요건을 충족하면, SIG Docs 리뷰어가 될 수 있다. 다른 SIG의 리뷰어는 SIG Docs의 리뷰어 자격에 반드시 별도로 지원해야 한다.

지원하려면, 다음을 수행한다.

  1. kubernetes/website 리포지터리 내 OWNERS_ALIASES 파일의 섹션에 여러분의 GitHub 사용자 이름을 추가하는 풀 리퀘스트를 연다.

    참고:

     자신을 추가할 위치가 확실하지 않으면, `sig-docs-ko-reviews` 에 추가한다.

  2. PR을 하나 이상의 SIG-Docs 승인자(sig-docs-{language}-owners 에 나열된 사용자 이름)에게 지정한다.

승인되면, SIG Docs 리더가 적당한 GitHub 팀에 여러분을 추가한다. 일단 추가되면, K8s-ci-robot이 새로운 풀 리퀘스트에서 리뷰어로 여러분을 할당하고 제안한다.

승인자

승인자는 병합하기 위해 풀 리퀘스트를 리뷰하고 승인한다. 승인자는 @kubernetes/sig-docs-{language}-owners GitHub 팀의 멤버이다.

승인자는 다음의 작업을 할 수 있다.

PR에 이미 /lgtm 이 있거나, 승인자도 /lgtm 코멘트를 남긴다면, PR은 자동으로 병합된다. SIG Docs 승인자는 추가적인 기술 리뷰가 필요치 않는 변경에 대해서만 /lgtm 을 남겨야 한다.

풀 리퀘스트 승인

승인자와 SIG Docs 리더는 website 리포지터리로 풀 리퀘스트를 병합할 수 있는 유일한 사람들이다. 이것은 특정한 책임이 따른다.

승인자 되기

요구 사항을 충족하면 SIG Docs 승인자가 될 수 있다. 다른 SIG의 승인자는 SIG Docs의 승인자 자격에 대해 별도로 신청해야 한다.

지원하려면 다음을 수행한다.

  1. kubernetes/website 리포지터리 내 OWNERS_ALIASES 파일의 섹션에 자신을 추가하는 풀 리퀘스트를 연다.

    참고:

    자신을 추가할 위치가 확실하지 않으면, `sig-docs-ko-owners` 에 추가한다.

  2. PR에 한 명 이상의 현재 SIG Docs 승인자를 지정한다.

승인되면, SIG Docs 리더가 적당한 GitHub 팀에 여러분을 추가한다. 일단 추가되면, @k8s-ci-robot이 새로운 풀 리퀘스트에서 승인자로 여러분을 할당하고 제안한다.

다음 내용

2 - PR 랭글러(PR Wrangler)

SIG Docs 승인자는 리포지터리에 대해 일주일 동안 교대로 풀 리퀘스트 관리를 수행한다.

이 섹션은 PR 랭글러의 의무에 대해 다룬다. 좋은 리뷰 제공에 대한 자세한 내용은 변경 사항 리뷰하기를 참고한다.

의무

PR 랭글러는 일주일 간 매일 다음의 일을 해야 한다.

참고:

PR 랭글러 업무는 현지화 PR (영문이 아닌 PR)에는 적용되지 않는다. 현지화 팀은 해당 언어 PR 리뷰를 위한 자체적인 프로세스와 팀을 보유하고 있다. 다만, 현지화 PR의 레이블이 정확하게 지정되었는지 확인하거나, 언어와 무관한 작은 PR(링크 업데이트 등)을 리뷰하거나, 또는 오랫동안 방치된 PR (6개월보다 더 이전에 생성되었고 한 달 이상 업데이트가 없는 PR)에 대해 리뷰어나 기여자를 태그 하는 것은 종종 도움이 된다.

랭글러를 위해 도움이 되는 GitHub 쿼리

다음의 쿼리는 랭글러에게 도움이 된다. 이 쿼리들을 수행하여 작업한 후에는, 리뷰할 나머지 PR 목록은 일반적으로 작다. 이 쿼리들은 특히 현지화 PR을 제외한다. 모든 쿼리는 마지막 쿼리를 제외하고 메인 브렌치를 대상으로 한다.

랭글러를 위한 유용한 Prow 명령어

# 한글 레이블 추가
/language ko

# 둘 이상의 커밋인 경우 PR에 스쿼시 레이블 추가
/label tide/merge-method-squash

# Prow를 통해 PR 제목 변경(예: 진행 중인 작업(work-in-progress) [WIP] 또는 PR의 더 상세한 내용)
/retitle [WIP] <TITLE>

풀 리퀘스트를 종료하는 시기

리뷰와 승인은 PR 대기열을 최신 상태로 유지하는 도구 중 하나이다. 또 다른 도구는 종료(closure)이다.

다음의 상황에서 PR을 닫는다.

풀 리퀘스트를 닫는 것을 두려워하지 말자. 기여자는 진행 중인 작업을 쉽게 다시 열고 다시 시작할 수 있다. 종종 종료 통지는 작성자가 기여를 재개하고 끝내도록 자극하는 것이다.

풀 리퀘스트를 닫으려면, PR에 /close 코멘트를 남긴다.

참고:

k8s-triage-robot이라는 봇은 90일 동안 활동이 없으면 이슈를 오래된 것(stale)으로 표시한다. 30일이 더 지나면 rotten으로 표시하고 종료한다. PR 랭글러는 14-30일 동안 활동이 없으면 이슈를 닫아야 한다.

PR 랭글러 섀도우 프로그램

2021년 말에, SIG Docs는 PR 랭글러 섀도우 프로그램을 도입했다. 이 프로그램은 새로운 기여자가 PR 랭글링 과정을 이해하는 데 도움을 주기 위해 도입되었다.

섀도우 되기

3 - 이슈 랭글러(Issue Wrangler)

PR 랭글러와 마찬가지로, 공식 승인자, 검토자 및 SIG Docs 구성원들은 리포지토리에 대해 일주일 동안 교대로 이슈 심사와 분류를 수행한다.

의무

이슈 랭글러는 일주일 간 매일 다음의 일을 해야 한다.

요구사항

랭글러를 위한 유용한 Prow 명령어

다음은 이슈 랭글러가 자주 사용하는 명령어이다.

# 이슈 다시 열기
/reopen

# kubernetes/website에 맞지 않는 이슈를 다른 리포지토리로 이전
/transfer[-issue]

# rotten 이슈의 상태 변경
/remove-lifecycle rotten

# stale 이슈의 상태 변경
/remove-lifecycle stale

# 이슈에 SIG 할당
/sig <sig_name>

# 특정 영역 추가
/area <area_name>

# 초보자에게 적합한 이슈
/good-first-issue

# 도움이 필요한 이슈
/help wanted

# 지원 관련 이슈 태그 지정
/kind support

# 이슈 심사 수락
/triage accepted

# 작업하지 않거나 아직 해결되지 않은 이슈 닫기
/close not-planned

더 많은 Prow 명령어는 Command Help 문서를 참조한다.

이슈를 종료하는 시점

오픈소스 프로젝트가 성공하려면 좋은 이슈 관리가 필수적이다. 그러나 리포지토리를 유지하고 기여자 및 작성자와 명확하게 소통하기 위해 이슈를 해결하는 것도 매우 중요하다.

다음과 같은 경우 이슈를 닫는다.

이슈를 닫으려면, 이슈에 /close 코멘트를 남긴다.