SIG Docs에 참여하기

• 1: 역할과 책임
• 2: PR 랭글러(PR Wrangler)
• 3: 이슈 랭글러(Issue Wrangler)

1 - 역할과 책임

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

• 모든 사람: 쿠버네티스 문서에 정기적으로 기여하는 기여자
• 멤버: 이슈를 할당, 심사하고 풀 리퀘스트에 대한 구속력 없는 리뷰를 제공할 수 있다.
• 리뷰어: 문서의 풀 리퀘스트에 대한 리뷰를 리딩할 수 있으며 변경 사항에 대한 품질을 보증할 수 있다.
• 승인자: 문서에 대한 리뷰를 리딩하고 변경 사항을 병합할 수 있다

모든 사람

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

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

• kubernetes/website를 포함한 모든 쿠버네티스 리포지터리에서 이슈를 올린다.
• 풀 리퀘스트에 대해 구속력 없는 피드백을 제공한다.
• 현지화에 기여한다.
• 슬랙 또는 SIG docs 메일링 리스트에 개선을 제안한다.

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

• 기존 콘텐츠를 개선하거나, 새 콘텐츠를 추가하거나, 블로그 게시물 또는 사례연구 작성을 위해 풀 리퀘스트를 연다.
• 다이어그램, 그래픽 자산 그리고 포함할 수 있는 스크린캐스트와 비디오를 제작한다.

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

멤버

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

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

• 모든 사람에 나열된 모든 것을 한다.

• 풀 리퀘스트에 /lgtm 코멘트를 사용하여 LGTM(looks good to me) 레이블을 추가한다.

  참고:

  /lgtm 사용은 자동화를 트리거한다. 만약 구속력 없는 승인을 제공하려면, "LGTM" 코멘트를 남기는 것도 좋다!

• /hold 코멘트를 사용하여 풀 리퀘스트에 대한 병합을 차단한다.

• /assign 코멘트를 사용하여 풀 리퀘스트에 리뷰어를 지정한다.

• 풀 리퀘스트에 구속력 없는 리뷰를 제공한다.

• 자동화를 사용하여 이슈를 심사하고 분류한다.

• 새로운 기능에 대한 문서를 작성한다.

멤버 되기

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

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

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

   참고:

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

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

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

   • 이슈에서 후원자의 GitHub 사용자 이름을 코멘트로 추가한다. (@<GitHub-username>)

   • 슬랙 또는 이메일을 사용해 이슈 링크를 후원자에게 보낸다.

     후원자는 +1 투표로 여러분의 요청을 승인할 것이다. 후원자가 요청을 승인하면, 쿠버네티스 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 팀의 멤버이다.

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

• 모든 사람, 멤버 그리고 리뷰어 하위의 모든 목록을 할 수 있다.
• 코멘트에 /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의 승인자 자격에 대해 별도로 신청해야 한다.

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

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

   참고:

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

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

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

다음 내용

• 모든 승인자가 교대로 수행하는 역할인 PR 랭글러에 대해 읽어보기

2 - PR 랭글러(PR Wrangler)

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

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

의무

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

• 품질 및 스타일과 콘텐츠 가이드 준수 여부를 확인하기 위해 열린(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 코멘트를 받아야 한다.
  • 스타일 지침을 충족하지 않더라도 기술적으로 정확한 콘텐츠라면 수락하는 것을 고려한다. 수정 사항을 승인함과 동시에, 스타일 문제를 해결하기 위한 새로운 이슈를 생성한다. 이러한 수정 이슈는 보통 good first issues로 작성할 수 있다.
  • 스타일 수정 작업을 good first issue로 활용하는 것은 새로운 기여자들이 원활하게 합류할 수 있도록 쉬운 과제를 꾸준히 제공하는 좋은 방법이다.
• 또한 참조 문서 생성 시 코드에 대한 풀 리퀘스트가 있는지 확인하고, 직접 리뷰하거나 (필요하다면) 도움을 요청한다.
• 매일 새로 올라오는 이슈를 심사하고 태그를 지정하는 이슈 랭글러를 보조한다. 이슈 심사와 분류를 참고하여 SIG Docs가 메타데이터를 사용하는 방법에 대한 지침을 확인한다.

랭글러를 위해 도움이 되는 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 @<manager'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 서명 없이 어떤 것도 병합되지 않도록 보장하는 저위험(row-risk) 방식이다.

• 작성자가 2주 이상 동안 코멘트나 피드백에 응답하지 않았다.

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

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

PR 랭글러 섀도우 프로그램

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

섀도우 되기

• PR 랭글러 섀도우 활동에 관심이 있다면, PR 랭글러 위키 페이지에서 올해의 PR 랭글링 스케줄을 확인하고 지원한다.

• 다른 사람들은 특정 주간에 배정된 PR 랭글러의 섀도우 기여를 요청하기 위해 #sig-docs 슬랙 채널 을 통해 문의할 수 있다. 궁금한 점이 있다면 언제든 SIG Docs 공동 의장 및 리드(co-chairs/leads) 중 한 명에게 문의한다.

• PR 랭글러 섀도우를 신청했다면, 쿠버네티스 슬랙에서 해당 PR 랭글러에게 자기소개를 한다.

3 - 이슈 랭글러(Issue Wrangler)

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

의무

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

• 새로운 이슈를 매일 분류하고 태깅한다. SIG Docs에서 메타데이터를 사용하는 방법에 대한 지침은 이슈 심사 를 참조한다.
• kubernetes/website 리포지토리 내 활동이 없거나(stale) 오래된(rotten) 이슈들을 주시한다.
• 이슈 보드를 관리한다.

요구사항

• 쿠버네티스 조직의 활동적인 멤버여야 한다.
• 쿠버네티스에 대한 최소 15개 이상의 사소하지 않은 기여가 있어야 한다. (이 중 일정 부분은 kubernetes/website 리포지토리에 대한 기여여야 한다).
• 이미 비공식적으로 해당 역할을 수행하고 있어야 한다.

랭글러를 위한 유용한 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 문서를 참조한다.

이슈를 종료하는 시점

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

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

• 유사한 이슈가 여러 번 보고된 경우. 먼저 /triage duplicate 로 태깅하고, 메인 이슈에 링크하고 해당 이슈를 닫는다. 작성자에게 원본 이슈로 안내하는 것이 좋다.
• 작성자가 제시한 이슈를 제공된 정보만으로 이해하고 해결하는 것이 매우 어려운 경우. 그러나 작성자가 이슈를 재현할 수 있다면, 더 자세한 정보를 제공하거나 이슈를 재개하도록 권장한다.
• 동일한 기능이 다른 곳에 이미 구현되어 있는 경우. 이슈를 닫고 작성자를 적절한 곳으로 안내할 수 있다.
• 보고된 이슈가 현재 계획되어 있지 않거나 프로젝트 목표와 일치하지 않는 경우.
• 이슈가 스팸으로 보이며 명백히 관련이 없는 경우.
• 이슈가 외부 제한 사항이나 의존성과 관련되어 있으며 프로젝트의 통제 범위를 벗어난 경우.

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