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 [팀]에는 두 분류가 있다.
- 승인자와 리더를 위한
@sig-docs-{language}-owners
- 리뷰어를 위한
@sig-docs-{language}-reviews
그룹의 전원과 의사소통하기 위해서
각각 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 승인자가 풀 리퀘스트를 병합하는 것을 제한한다.
작동 방식은 다음과 같다.
- 풀 리퀘스트에
lgtm
과 approve
레이블이 있고, hold
레이블이 없고,
모든 테스트를 통과하면 풀 리퀘스트는 자동으로 병합된다.
- 쿠버네티스 조직의 멤버와 SIG Docs 승인자들은 지정된 풀 리퀘스트의
자동 병합을 방지하기 위해 코멘트를 추가할 수 있다(코멘트에
/hold
추가 또는
/lgtm
코멘트 보류).
- 모든 쿠버네티스 멤버는 코멘트에
/lgtm
을 추가해서 lgtm
레이블을 추가할 수 있다.
- SIG Docs 승인자들만이 코멘트에
/approve
를
추가해서 풀 리퀘스트를 병합할 수 있다. 일부 승인자들은
PR Wrangler 또는 SIG Docs 의장과
같은 특정 역할도 수행한다.
다음 내용
쿠버네티스 문서화에 기여하는 일에 대한 보다 많은 정보는 다음 문서를 참고한다.
1 - 역할과 책임
누구나 쿠버네티스에 기여할 수 있다. SIG Docs에 대한 기여가 커짐에 따라,
커뮤니티의 다양한 멤버십을 신청할 수 있다.
이러한 역할을 통해 커뮤니티 내에서 더 많은 책임을 질 수 있다.
각 역할마다 많은 시간과 노력이 필요하다. 역할은 다음과 같다.
- 모든 사람: 쿠버네티스 문서에 정기적으로 기여하는 기여자
- 멤버: 이슈를 할당, 심사하고 풀 리퀘스트에 대한 구속력 없는 리뷰를 제공할 수 있다.
- 리뷰어: 문서의 풀 리퀘스트에 대한 리뷰를 리딩할 수 있으며 변경 사항에 대한 품질을 보증할 수 있다.
- 승인자: 문서에 대한 리뷰를 리딩하고 변경 사항을 병합할 수 있다
모든 사람
GitHub 계정을 가진 누구나 쿠버네티스에 기여할 수 있다. SIG Docs는 모든 새로운 기여자를 환영한다!
모든 사람은 다음의 작업을 할 수 있다.
CLA에 서명 후에 누구나 다음을 할 수 있다.
- 기존 콘텐츠를 개선하거나, 새 콘텐츠를 추가하거나, 블로그 게시물 또는 사례연구 작성을 위해 풀 리퀘스트를 연다.
- 다이어그램, 그래픽 자산 그리고 포함할 수 있는 스크린캐스트와 비디오를 제작한다.
자세한 내용은 새로운 콘텐츠 기여하기를 참고한다.
멤버
멤버는 kubernetes/website
에 여러 개의 풀 리퀘스트를 제출한
사람이다. 멤버는
쿠버네티스 GitHub 조직의 회원이다.
멤버는 다음의 작업을 할 수 있다.
-
모든 사람에 나열된 모든 것을 한다.
-
풀 리퀘스트에 /lgtm
코멘트를 사용하여 LGTM(looks good to me) 레이블을 추가한다.
참고: /lgtm
사용은 자동화를 트리거한다. 만약 구속력 없는 승인을 제공하려면,
"LGTM" 코멘트를 남기는 것도 좋다!
-
/hold
코멘트를 사용하여 풀 리퀘스트에 대한 병합을 차단한다.
-
/assign
코멘트를 사용하여 풀 리퀘스트에 리뷰어를 지정한다.
-
풀 리퀘스트에 구속력 없는 리뷰를 제공한다.
-
자동화를 사용하여 이슈를 심사하고 분류한다.
-
새로운 기능에 대한 문서를 작성한다.
멤버 되기
최소 5개의 실질적인 풀 리퀘스트를 제출하고 다른
요구 사항을 충족시킨 후, 다음의 단계를 따른다.
-
멤버십을 후원해줄 두 명의
리뷰어 또는 승인자를
찾는다.
슬랙의 #sig-docs 채널 또는
SIG Docs 메일링 리스트에서 후원을 요청한다.
참고: SIG Docs 멤버 개인에게 직접 email을 보내거나
슬랙 다이렉트 메시지를 보내지 않는다. 반드시 지원서를 제출하기 전에 후원을 요청해야 한다.
-
kubernetes/org
리포지터리에
GitHub 이슈를 등록한다.
Organization Membership Request 이슈 템플릿을 사용한다.
-
후원자에게 GitHub 이슈를 알린다. 다음 중 하나를 수행할 수 있다.
-
이슈에서 후원자의 GitHub 사용자 이름을 코멘트로 추가한다. (@<GitHub-username>
)
-
슬랙 또는 이메일을 사용해 이슈 링크를 후원자에게 보낸다.
후원자는 +1
투표로 여러분의 요청을 승인할 것이다. 후원자가 요청을 승인하면,
쿠버네티스 GitHub 관리자가 여러분을 멤버로 추가한다.
축하한다!
만약 멤버십이 수락되지 않으면 피드백을 받게 될 것이다.
피드백의 내용을 해결한 후, 다시 지원하자.
-
여러분의 이메일 계정으로 수신된 쿠버네티스 GitHub 조직으로의 초대를 수락한다.
참고: GitHub은 초대를 여러분 계정의 기본 이메일 주소로 보낸다.
리뷰어
리뷰어는 열린 풀 리퀘스트를 리뷰할 책임이 있다. 멤버 피드백과는 달리,
여러분은 리뷰어의 피드백을 반드시 해결해야 한다. 리뷰어는
@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의 리뷰어 자격에
반드시 별도로 지원해야 한다.
지원하려면, 다음을 수행한다.
-
kubernetes/website
리포지터리 내
OWNERS_ALIASES 파일의 섹션에
여러분의 GitHub 사용자 이름을 추가하는 풀 리퀘스트를 연다.
참고: 자신을 추가할 위치가 확실하지 않으면, sig-docs-ko-reviews
에 추가한다.
-
PR을 하나 이상의 SIG-Docs 승인자(sig-docs-{language}-owners
에
나열된 사용자 이름)에게 지정한다.
승인되면, SIG Docs 리더가 적당한 GitHub 팀에 여러분을 추가한다. 일단 추가되면,
K8s-ci-robot이
새로운 풀 리퀘스트에서 리뷰어로 여러분을 할당하고 제안한다.
승인자
승인자는 병합하기 위해 풀 리퀘스트를 리뷰하고 승인한다. 승인자는
@kubernetes/sig-docs-{language}-owners
GitHub 팀의 멤버이다.
승인자는 다음의 작업을 할 수 있다.
- 모든 사람, 멤버 그리고 리뷰어 하위의 모든 목록을 할 수 있다.
- 코멘트에
/approve
를 사용해서 풀 리퀘스트를 승인하고, 병합해서 기여자의 컨텐츠를 게시한다.
- 스타일 가이드 개선을 제안한다.
- 문서 테스트 개선을 제안한다.
- 쿠버네티스 웹사이트 또는 다른 도구 개선을 제안한다.
PR에 이미 /lgtm
이 있거나, 승인자도 /lgtm
코멘트를 남긴다면,
PR은 자동으로 병합된다. SIG Docs 승인자는 추가적인 기술 리뷰가 필요치 않는 변경에 대해서만
/lgtm
을 남겨야 한다.
풀 리퀘스트 승인
승인자와 SIG Docs 리더는 website 리포지터리로 풀 리퀘스트를 병합할 수 있는
유일한 사람들이다. 이것은 특정한 책임이 따른다.
-
승인자는 PR들을 리포지터리에 병합하는 /approve
명령을 사용할 수 있다.
경고: 부주의한 머지로 인해 사이트를 파괴할 수 있으므로, 머지할 때에 그 의미를 확인해야 한다.
-
제안된 변경이
컨트리뷰션 가이드 라인에 적합한지 확인한다.
질문이 생기거나 확실하지 않다면 자유롭게
추가 리뷰를 요청한다.
-
PR을 /approve
하기 전에 Netlify 테스트 결과를 검토한다.
-
승인 전에 PR에 대한 Netlify 프리뷰 페이지를 방문하여, 제대로 보이는지 확인한다.
-
주간 로테이션을 위해
PR Wrangler 로테이션 스케줄에
참여한다. SIG Docs는 모든 승인자들이 이 로테이션에 참여할 것으로 기대한다. 자세한 내용은
PR 랭글러(PR wrangler)를
참고한다.
승인자 되기
요구 사항을
충족하면 SIG Docs 승인자가 될 수 있다.
다른 SIG의 승인자는 SIG Docs의 승인자 자격에 대해
별도로 신청해야 한다.
지원하려면 다음을 수행한다.
-
kubernetes/website
리포지터리 내
OWNERS_ALIASES
파일의 섹션에 자신을 추가하는 풀 리퀘스트를 연다.
참고: 자신을 추가할 위치가 확실하지 않으면, sig-docs-ko-owners
에 추가한다.
-
PR에 한 명 이상의 현재 SIG Docs 승인자를 지정한다.
승인되면, SIG Docs 리더가 적당한 GitHub 팀에 여러분을 추가한다. 일단 추가되면,
@k8s-ci-robot이
새로운 풀 리퀘스트에서 승인자로 여러분을 할당하고 제안한다.
다음 내용
- 모든 승인자가 교대로 수행하는 역할인 PR 랭글러에 대해 읽어보기
2 - PR 랭글러(PR Wrangler)
SIG Docs 승인자는 리포지터리에 대해 일주일 동안 교대로 풀 리퀘스트 관리를 수행한다.
이 섹션은 PR 랭글러의 의무에 대해 다룬다. 좋은 리뷰 제공에 대한 자세한 내용은 Reviewing changes를 참고한다.
의무
PR 랭글러는 일주일 간 매일 다음의 일을 해야 한다.
- 매일 새로 올라오는 이슈를 심사하고 태그를 지정한다. SIG Docs가 메타데이터를 사용하는 방법에 대한 지침은 이슈 심사 및 분류를 참고한다.
- 스타일과 콘텐츠 가이드를 준수하는지에 대해 열린(open) 풀 리퀘스트를 매일 리뷰한다.
- 가장 작은 PR(
size/XS
)부터 시작하고, 가장 큰(size/XXL
) PR까지 리뷰한다. 가능한 한 많은 PR을 리뷰한다.
- PR 기여자들이 CLA에 서명했는지 확인한다.
- CLA에 서명하지 않은 기여자에게 CLA에 서명하도록 알리려면 이 스크립트를 사용한다.
- 제안된 변경 사항에 대한 피드백을 제공하고 다른 SIG의 멤버에게 기술 리뷰를 요청한다.
- 제안된 콘텐츠 변경에 대해 PR에 인라인 제안(inline suggestion)을 제공한다.
- 내용을 확인해야 하는 경우, PR에 코멘트를 달고 자세한 내용을 요청한다.
- 관련
sig/
레이블을 할당한다.
- 필요한 경우, 파일의 머리말(front matter)에 있는
reviewers:
블록의 리뷰어를 할당한다.
- PR에
@kubernetes/<sig>-pr-reviews
코멘트를 남겨 SIG에 리뷰를 요청할 수도 있다.
- PR을 병합하려면 승인을 위한
approve
코멘트를 사용한다. 준비가 되면 PR을 병합한다.
- 병합하기 전에 PR은 다른 멤버의
/lgtm
코멘트를 받아야 한다.
- [스타일 지침]을 충족하지 않지만 기술적으로는 정확한 PR은 수락하는 것을 고려한다. 스타일 문제를 해결하는
good first issue
레이블의 새로운 이슈를 올리면 된다.
- 스타일 지침을 충족하지 않지만
기술적으로는 정확한 PR은 수락하는 쪽으로 고려한다.
변경 사항을 승인하면, 스타일 이슈에 대한 새 이슈를 연다.
보통 이러한 스타일 수정 이슈는 좋은 첫 이슈로 지정할 수 있다.
- 스타일 수정 이슈를 좋은 첫 이슈로 표시하면 비교적 쉬운 작업을 공급하여
새로운 기여자가 참여하는 것을 장려할 수 있다.
랭글러를 위해 도움이 되는 GitHub 쿼리
다음의 쿼리는 랭글러에게 도움이 된다.
이 쿼리들을 수행하여 작업한 후에는, 리뷰할 나머지 PR 목록은 일반적으로 작다.
이 쿼리들은 특히 현지화 PR을 제외한다. 모든 쿼리는 마지막 쿼리를 제외하고 메인 브렌치를 대상으로 한다.
- CLA 서명 없음, 병합할 수 없음:
CLA에 서명하도록 기여자에게 상기시킨다. 봇과 사람이 이미 알렸다면, PR을 닫고
CLA에 서명한 후 PR을 열 수 있음을 알린다.
작성자가 CLA에 서명하지 않은 PR은 리뷰하지 않는다!
- LGTM 필요:
멤버의 LGTM이 필요한 PR을 나열한다. PR에 기술 리뷰가 필요한 경우, 봇이 제안한 리뷰어 중 한 명을 지정한다. 콘텐츠에 대한 작업이 필요하다면, 제안하거나 인라인 피드백을 추가한다.
- LGTM 보유, 문서 승인 필요:
병합을 위해
/approve
코멘트가 필요한 PR을 나열한다.
- 퀵윈(Quick Wins): 명확한 결격 사유가 없는 메인 브랜치에 대한 PR을 나열한다. ([XS, S, M, L, XL, XXL] 크기의 PR을 작업할 때 크기 레이블에서 "XS"를 변경한다)
- 메인 브랜치이외의 브랜치에 대한 PR:
dev-
브랜치에 대한 것일 경우, 곧 출시될 예정인 릴리스이다. /assign @<meister's_github-username>
을 사용하여 문서 릴리스 관리자를 할당한다. 오래된 브랜치에 대한 PR인 경우, PR 작성자가 가장 적합한 브랜치를 대상으로 하고 있는지 여부를 파악할 수 있도록 도와준다.
랭글러를 위한 유용한 Prow 명령어
# 한글 레이블 추가
/language ko
# 둘 이상의 커밋인 경우 PR에 스쿼시 레이블 추가
/label tide/merge-method-squash
# Prow를 통해 PR 제목 변경(예: 진행 중인 작업(work-in-progress) [WIP] 또는 PR의 더 상세한 내용)
/retitle [WIP] <TITLE>
풀 리퀘스트를 종료하는 시기
리뷰와 승인은 PR 대기열을 최신 상태로 유지하는 도구 중 하나이다. 또 다른 도구는 종료(closure)이다.
다음의 상황에서 PR을 닫는다.
-
작성자가 CLA에 2주 동안 서명하지 않았다.
작성자는 CLA에 서명한 후 PR을 다시 열 수 있다. 이는 어떤 것도 CLA 서명없이 병합되지 않게 하는 위험이 적은 방법이다.
-
작성자가 2주 이상 동안 코멘트나 피드백에 응답하지 않았다.
풀 리퀘스트를 닫는 것을 두려워하지 말자. 기여자는 진행 중인 작업을 쉽게 다시 열고 다시 시작할 수 있다. 종종 종료 통지는 작성자가 기여를 재개하고 끝내도록 자극하는 것이다.
풀 리퀘스트를 닫으려면, PR에 /close
코멘트를 남긴다.
참고: k8s-triage-robot
이라는 봇은 90일 동안 활동이 없으면 이슈를 오래된 것(stale)으로 표시한다. 30일이 더 지나면 rotten으로 표시하고 종료한다. PR 랭글러는 14-30일 동안 활동이 없으면 이슈를 닫아야 한다.
PR 랭글러 섀도우 프로그램
2021년 말에, SIG Docs는 PR 랭글러 섀도우 프로그램을 도입했다. 이 프로그램은 새로운 기여자가 PR 랭글링 과정을 이해하는 데 도움을 주기 위해 도입되었다.
섀도우 되기