변경 사항 리뷰하기

이 섹션은 콘텐츠를 리뷰하는 방법에 대해 설명한다.

1 - 풀 리퀘스트 리뷰하기

누구나 문서화에 대한 풀 리퀘스트를 리뷰할 수 있다. 쿠버네티스 website 리포지터리의 풀 리퀘스트 섹션을 방문하여 열린(open) 풀 리퀘스트를 확인한다.

문서화에 대한 풀 리퀘스트를 리뷰하는 것은 쿠버네티스 커뮤니티에 자신을 소개하는 훌륭한 방법이다. 아울러, 코드 베이스(code base)를 배우고 다른 기여자와 신뢰를 구축하는 데 도움이 된다.

리뷰하기 전에, 다음을 수행하는 것이 좋다.

시작하기 전에

리뷰를 시작하기 전에 다음을 명심하자.

리뷰 과정

일반적으로, 영어로 콘텐츠와 스타일에 대한 풀 리퀘스트를 리뷰한다. 그림 1은 리뷰 과정의 단계를 보여 준다. 각 단계에 대한 상세 사항은 아래에 나와 있다.

flowchart LR subgraph fourth[리뷰 시작] direction TB S[ ] -.- M[코멘트 작성] --> N[변경 사항 리뷰] N --> O[새 기여자가 어떤 코멘트를
반영할지 선택해야 함] end subgraph third[PR 선택] direction TB T[ ] -.- J[본문과 코멘트 확인]--> K[Netlify 미리보기 빌드로
변경 사항 미리보기] end A[열려 있는 PR 목록 확인]--> B[레이블을 이용하여
PR을 필터링] B --> third --> fourth classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px; classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000 class A,B,J,K,M,N,O grey class S,T spacewhite class third,fourth white

그림 1. 리뷰 과정 절차.

  1. https://github.com/kubernetes/website/pulls로 이동한다. 쿠버네티스 website와 문서에 대한 모든 열린 풀 리퀘스트 목록이 표시된다.

  2. 다음 레이블 중 하나 또는 모두를 사용하여 열린 PR을 필터링한다.

    또한, PR이 진행 중인 작업으로 표시되지 않았는지 확인한다. work in progress 레이블을 사용하는 PR은 아직 리뷰할 준비가 되지 않은 PR이다.

  3. 리뷰할 PR을 선택한 후, 다음을 통해 변경 사항을 이해한다.

  4. Files changed 탭으로 이동하여 리뷰를 시작한다.

    1. 코멘트를 달려는 줄 옆에 있는 + 기호를 클릭한다.
    2. 행에 대한 의견을 작성하고 Add single comments(작성할 의견이 하나만 있는 경우) 또는 Start a review(작성할 의견이 여러 개인 경우)를 클릭한다.
    3. 완료되면, 페이지 상단에서 Review changes 를 클릭한다. 여기에서 리뷰에 대한 요약을 추가한다(기여자에게 긍정적인 의견을 남겨주기 바란다!). 항상 "Comment" 를 선택해야 한다

리뷰 체크리스트

리뷰할 때, 다음을 시작점으로 사용한다.

언어와 문법

콘텐츠

문서화

고려해야 할 몇 가지 사항:

블로그

블로그 게시물에 대한 초기 피드백은 Google Doc 또는 HackMD를 통해 환영한다. #sig-docs-blog 슬랙 채널을 통해 미리 의견을 낸다.

블로그 PR을 검토하기 전에 블로그 가이드라인과 블로그 게시물 및 사례 연구 제출을 숙지한다.

evergreen 게시물이 무엇인지와 어떤 기준으로 게시물이 evergreen인지 판단하는지에 대해서도 숙지해야 한다.

블로그 게시물에는 직접 인용과 간접 화법이 포함될 수 있다. 누군가에게 기인하거나 발생한 대화의 일부에 대해 다른 표현을 제안하는 것은 피한다. 원문 화자의 문법이 정확하지 않다고 생각하더라도 마찬가지이다. 이러한 경우에도 명백히 잘못된 경우가 아니면 작성자가 제안한 구두점을 존중한다.

프로젝트로서, 쿠버네티스 프로젝트가 무기한 유지 관리를 약속하는 경우에만 블로그 게시물을 유지 관리됨(evergreen: true 표시)으로 표시한다. 일부 블로그 게시물은 반드시 유지 관리되어야 하며, 우리는 항상 릴리스 공지를 항상 evergreen으로 표시한다. 이 점을 어떻게 검토해야 할지 확실하지 않은 경우 다른 기여자에게 문의한다.

콘텐츠 가이드는 블로그 게시물과 이를 추가하는 PR에 무조건 적용된다. 가이드의 일부 제한 사항은 문서에만 적용되며, 블로그 게시물에는 적용되지 않는다는 점에 유의한다.

마크다운 소스가 올바른 페이지 콘텐츠 유형 및 / 또는 layout을 사용하고 있는지 확인한다.

기타

리뷰어로서, PR에서 공백 문제나 오타 등 크게 중요하지 않은 사소한 이슈들을 발견하는 경우, 리뷰 앞에 nit:을 붙인다. 이렇게 함으로써 기여자가 해당 피드백이 크게 중요하지 않다는 것을 알 수 있다.

nit 으로 표시된 피드백을 제외하고 모든 이슈들을 해결한 PR은 병합할 수 있다. 이러한 경우, 아직 해결되지 않는 nit 사항들에 대하여 새롭게 이슈를 여는 것을 권장한다. 또한 새로운 이슈를 Good First Issue로써 표시할 수 있는지에 대해 고려해본다. 가능한 경우, 이것은 새로운 기여자에게 좋은 소스가 된다.

2 - 승인자와 리뷰어의 리뷰

SIG Docs 리뷰어와 승인자는 변경 사항을 리뷰할 때 몇 가지 추가 작업을 수행한다.

매주 특정 문서 승인자 역할의 지원자가 풀 리퀘스트를 심사하고 리뷰한다. 이 사람은 일주일 동안 "PR 랭글러(Wrangler)"이다. 자세한 정보는 PR 랭글러 스케줄러를 참고한다. PR 랭글러가 되려면, 매주 SIG Docs 회의에 참석하고 자원한다. 이번 주에 해당 일정이 없는 경우에도, 아직 리뷰 중이 아닌 풀 리퀘스트(PR)를 여전히 리뷰할 수 있다.

로테이션 외에도, 봇은 영향을 받는 파일의 소유자를 기반으로 PR에 대한 리뷰어와 승인자를 할당한다.

PR 리뷰

쿠버네티스의 문서는 쿠버네티스의 코드 리뷰 프로세스를 따른다.

풀 리퀘스트 리뷰에 설명된 모든 내용이 적용되지만, 리뷰어와 승인자도 다음을 수행해야 한다.

다른 사람의 PR에 커밋

PR 코멘트를 남기는 것이 도움이 되지만, 대신 다른 사람의 PR에 커밋을 해야 하는 경우가 있다.

다른 사람이 명시적으로 요청하거나, 오랫동안 중단된 PR을 재개하려는 경우가 아니라면 다른 사람에게서 "가져오지" 않는다. 단기적으로는 작업이 빠를 수 있지만, 그 사람이 기여할 기회를 박탈하게 된다.

사용할 프로세스는 이미 PR의 범위에 있는 파일을 편집해야 하는지, 또는 PR이 아직 다루지 않은 파일을 편집해야 하는지에 따라 다르다.

다음 중 하나에 해당하면 다른 사람의 PR에 커밋할 수 없다.

리뷰를 위한 Prow 명령

Prow는 풀 리퀘스트 (PR)에 대한 작업을 실행하는 쿠버네티스 기반 CI/CD 시스템이다. Prow는 챗봇 스타일 명령으로 쿠버네티스 조직 전체에서 레이블 추가와 제거, 이슈 종료 및 승인자 할당과 같은 GitHub 작업을 처리할 수 있다. /<command-name> 형식을 사용하여 Prow 명령을 GitHub 코멘트로 입력한다.

리뷰어와 승인자가 사용하는 가장 일반적인 Prow 명령은 다음과 같다.

리뷰를 위한 Prow 명령
Prow 명령 역할 제한 설명
/lgtm 조직 멤버 PR 리뷰를 마치고 변경 사항에 만족했음을 나타낸다.
/approve 승인자 PR을 병합(merge)하기 위해 승인한다.
/assign 누구나 PR을 리뷰하거나 승인할 사람을 지정한다.
/close 조직 멤버 이슈 또는 PR을 닫는다.
/hold 누구나 자동으로 병합할 수 없음을 나타내는 do-not-merge/hold 레이블을 추가한다.
/hold cancel 누구나 do-not-merge/hold 레이블을 제거한다.

PR에서 사용할 수 있는 명령어들을 보려면 Prow 명령 레퍼런스를 참고한다.

이슈 심사와 분류

일반적으로, SIG Docs는 쿠버네티스 이슈 심사 프로세스를 따르며 동일한 레이블을 사용한다.

이 GitHub 이슈 필터는 심사가 필요한 이슈를 찾는다.

이슈 심사

  1. 이슈 확인
  1. 우선순위 레이블을 추가한다( 이슈 심사 가이드라인은 우선순위 레이블을 자세히 정의함).
이슈 레이블
레이블 설명
priority/critical-urgent 이 작업을 지금 즉시 수행한다.
priority/important-soon 3개월 이내에 이 작업을 수행한다.
priority/important-longterm 6개월 이내에 이 작업을 수행한다.
priority/backlog 무기한 연기할 수 있다. 자원이 있을 때 수행한다.
priority/awaiting-more-evidence 잠재적으로 좋은 이슈에 대해 잊지 않도록 표시한다.
help 또는 good first issue 쿠버네티스나 SIG Docs 경험이 거의 없는 사람에게 적합하다. 자세한 내용은 도움이 필요함 및 좋은 첫 번째 이슈 레이블을 참고한다.

재량에 따라, 이슈의 소유권을 가져와서 PR을 제출한다 (특히, 이미 수행 중인 작업과 관련이 있거나 빠르다면).

이슈 심사에 대해 질문이 있다면, 슬랙의 #sig-docs 채널이나 kubernetes-sig-docs 메일링리스트에 문의한다.

이슈 레이블 추가와 제거

레이블을 추가하려면, 다음의 형식 중 하나로 코멘트를 남긴다.

레이블을 제거하려면, 다음의 형식 중 하나로 코멘트를 남긴다.

두 경우 모두, 사용하려는 레이블은 이미 존재하는 레이블이어야 한다. 존재하지 않는 레이블을 추가하려고 하면, 명령이 자동으로 무시된다.

모든 레이블 목록에 대해서는 website 리포지터리의 레이블 섹션을 참고한다. SIG Docs에서 모든 레이블을 사용하는 것은 아니다.

이슈의 lifecycle 레이블

이슈는 일반적으로 신속하게 열리고 닫힌다. 그러나, 가끔씩은 이슈가 열린 후 비활성 상태로 있다. 어떤 경우에는 이슈가 90일 이상 열려 있을 수도 있다.

이슈의 lifecycle 레이블
레이블 설명
lifecycle/stale 90일이 지나도 아무런 활동이 없는 이슈는 자동으로 오래된 것(stale)으로 표시된다. /remove-lifecycle stale 명령을 사용하여 라이프사이클을 수동으로 되돌리지 않으면 이슈가 자동으로 닫힌다.
lifecycle/frozen 90일 동안 활동이 없어도 이 레이블의 이슈는 오래된 것(stale)으로 바뀌지 않는다. 사용자는 priority/important-longterm 레이블이 있는 이슈처럼 90일보다 훨씬 오래 열려 있어야 하는 이슈에 이 레이블을 수동으로 추가한다.

특별한 이슈 유형의 처리

SIG Docs가 처리 방법을 문서화할 정도로 다음과 같은 유형의 이슈를 자주 경험하게 된다.

중복된 이슈

단일 문제에 대해 하나 이상의 이슈가 열려 있으면, 이를 단일 이슈로 합친다. 열린 상태를 유지할 이슈를 결정한 다음(또는 새로운 이슈를 열어야 함), 모든 관련 정보로 이동하여 관련 이슈를 연결해야 한다. 마지막으로, 동일한 문제를 설명하는 다른 모든 이슈에 triage/duplicate 레이블을 지정하고 닫는다. 하나의 이슈만 해결하는 것으로 혼동을 줄이고 같은 문제에 대한 중복 작업을 피할 수 있다.

깨진 링크 이슈

깨진 링크 이슈가 API 문서나 kubectl 문서에 있는 경우, 문제가 완전히 이해될 때까지 /priority critical-urgent 레이블을 할당한다. 다른 모든 깨진 링크 이슈는 수동으로 수정해야하므로, /priority important-longterm 를 할당한다.

블로그 이슈

쿠버네티스 블로그 항목은 시간이 지남에 따라 구식이 될 것으로 예상한다. 따라서, 1년 미만의 블로그 항목만 유지 관리한다. 1년이 지난 블로그 항목과 관련된 이슈일 경우, 수정하지 않고 이슈를 닫는다.

PR을 마감할 때 보내는 메시지에 기사 업데이트와 유지 관리 링크를 포함할 수 있다.

관련된 이유가 있는 경우 예외를 두는 것은 괜찮다.

지원 요청 또는 코드 버그 리포트

문서에 대한 일부 이슈는 실제로 기본 코드와 관련된 이슈이거나, 튜토리얼과 같은 무언가가 작동하지 않을 때 도움을 요청하는 것이다. 문서와 관련이 없는 이슈의 경우, triage/support 레이블과 함께 요청자에게 지원받을 수 있는 곳(슬랙, Stack Overflow)을 알려주며 이슈를 닫고, 기능 관련 버그에 대한 이슈인 경우, 관련 리포지터리를 코멘트로 남긴다(kubernetes/kubernetes 는 시작하기 좋은 곳이다).

지원 요청에 대한 샘플 응답은 다음과 같다.

이 이슈는 지원 요청과 비슷하지만
문서 관련 이슈와는 관련이 없는 것 같습니다.
[쿠버네티스 슬랙](https://slack.k8s.io/)의
`#kubernetes-users` 채널에서 질문을 하시기 바랍니다. 또한,
[Stack Overflow](https://stackoverflow.com/questions/tagged/kubernetes)와
같은 리소스를 검색하여 유사한 질문에 대한 답변을
얻을 수도 있다.

https://github.com/kubernetes/kubernetes 에서
쿠버네티스 기능 관련 이슈를 열 수도 있다.

문서에 대한 이슈인 경우 이 이슈를 다시 여십시오.

샘플 코드 버그 리포트 응답은 다음과 같다.

이 이슈는 문서에 대한 이슈보다 코드에 대한 이슈와
비슷합니다. https://github.com/kubernetes/kubernetes/issues 에서
이슈를 여십시오.

문서에 대한 이슈인 경우 이 이슈를 다시 여십시오.

스쿼시

승인자로서 풀 리퀘스트(PR)를 검토할 때 다음과 같은 다양한 경우가 있다.

기여자의 스쿼시 안내: 신규 기여자는 풀 리퀘스트(PR)에서 커밋을 스쿼시해야 한다는 사실을 모를 수 있다. 만약 그렇다면, 스쿼시를 하도록 안내하고, 유용한 정보 링크를 제공하고, 필요시 도움을 받을 수 있도록 제안한다. 유용한 링크는 다음과 같다.

기여자를 위한 커밋 스쿼시: 기여자가 커밋 스쿼시에 어려움을 겪거나 PR을 병합할 시간적 압박이 있는 경우, 기여자를 대신하여 스쿼시를 수행할 수 있다.

기여자에게는 스쿼시를 하지 않도록 안내

절대 스쿼시하지 않는다