K8s 문서에 기여하기

• 1: 콘텐츠 개선 제안
• 2: 새로운 콘텐츠 기여하기
• 2.1: 새로운 콘텐츠 기여하기에 대한 개요
• 2.2: 풀 리퀘스트 열기
• 3: 변경 사항 리뷰하기
• 3.1: 풀 리퀘스트 리뷰
• 3.2: 승인자와 리뷰어의 리뷰
• 4: SIG Docs에 참여하기
• 4.1: 역할과 책임
• 4.2: PR 랭글러(PR Wrangler)
• 5: 문서 스타일 개요
• 5.1: 새로운 주제의 문서 작성
• 6: 참조 문서 개요
• 7: 고급 기여
• 8: 쿠버네티스 문서 한글화 가이드

1 - 콘텐츠 개선 제안

쿠버네티스 문서에 문제가 있거나, 새로운 내용에 대한 아이디어가 있으면, 이슈를 연다. GitHub 계정과 웹 브라우저만 있으면 된다.

대부분의 경우, 쿠버네티스 문서에 대한 새로운 작업은 GitHub의 이슈로 시작된다. 그런 다음 쿠버네티스 기여자는 필요에 따라 이슈를 리뷰, 분류하고 태그를 지정한다. 다음으로, 여러분이나 다른 쿠버네티스 커뮤니티 멤버가 문제를 해결하기 위한 변경 사항이 있는 풀 리퀘스트를 연다.

이슈 열기

기존 콘텐츠에 대한 개선을 제안하거나, 오류를 발견하면, 이슈를 연다.

1. 오른쪽 사이드바에서 문서에 이슈 생성 링크를 클릭한다. 그러면 헤더가 미리 채워진 GitHub 이슈 페이지로 리디렉션된다.
2. 개선을 위한 문제나 제안 사항을 설명한다. 가능한 한 많은 정보를 제공한다.
3. Submit new issue 를 클릭한다.

이슈를 제출한 후, 가끔 확인하거나 GitHub 알림을 켜자. 리뷰어와 다른 커뮤니티 멤버가 이슈에 대한 조치를 취하기 전에 여러분에게 질문을 할 수 있다.

새로운 콘텐츠 제안

새로운 콘텐츠에 대한 아이디어가 있지만, 어디로 가야 할지 확실하지 않은 경우에도 이슈를 제기할 수 있다. 다음 중 하나를 선택하면 된다.

• 콘텐츠가 속한 섹션에서 기존 페이지를 선택하고 이슈 생성하기 를 클릭한다.
• GitHub으로 이동하여 이슈를 직접 제기한다.

이슈를 제기하는 좋은 방법

이슈를 제기할 때 다음의 사항에 유의한다.

• 명확하게 이슈에 대한 설명을 제공한다. 구체적으로 무엇이 누락되었거나, 오래되었거나, 잘못되었거나, 개선이 필요한 사항인지를 설명한다.
• 이 이슈가 사용자에게 미치는 영향을 설명한다.
• 주어진 이슈의 범위를 합리적인 작업 단위로 제한한다. 넓은 범위에 대한 이슈의 경우 더 작은 이슈로 분류한다. 예를 들어, "보안 문서 수정"은 너무 광범위하지만, "'네트워크 접근 제한' 주제에 세부 사항 추가"는 실행할 수 있을 정도로 구체적이다.
• 기존 이슈를 검색하여 새로운 이슈와 관련이 있거나 비슷한 것이 있는지 확인한다.
• 새로운 이슈가 다른 이슈나 풀 리퀘스트와 관련이 있는 경우, 전체 URL이나 # 문자로 시작하는 이슈나 풀 리퀘스트의 번호로 참고한다. 예를 들면, #987654 와 관련있습니다. 와 같이 하면 된다.
• 행동 강령을 따른다. 동료 기여자를 존중한다. 예를 들어, "문서가 끔찍하다"는 도움이 되지 않거나 예의 바르지 않은 피드백이다.

2 - 새로운 콘텐츠 기여하기

2.1 - 새로운 콘텐츠 기여하기에 대한 개요

이 섹션에는 새로운 콘텐츠를 기여하기 전에 알아야 할 정보가 있다.

기여하기에 대한 기본

• 마크다운(Markdown)으로 쿠버네티스 문서를 작성하고 Hugo를 사용하여 쿠버네티스 사이트를 구축한다.
• 소스는 GitHub에 있다. 쿠버네티스 문서는 /content/ko/docs/ 에서 찾을 수 있다. 일부 참조 문서는 update-imported-docs/ 디렉터리의 스크립트에서 자동으로 생성된다.
• 페이지 템플릿은 Hugo에서 문서 콘텐츠의 프리젠테이션을 제어한다.
• 표준 Hugo 단축코드(shortcode) 이외에도 설명서에서 여러 사용자 정의 Hugo 단축코드를 사용하여 콘텐츠 표시를 제어한다.
• 문서 소스는 /content/ 에서 여러 언어로 제공된다. 각 언어는 ISO 639-1 표준에 의해 결정된 2문자 코드가 있는 자체 폴더가 있다. 예를 들어, 한글 문서의 소스는 /content/ko/docs/ 에 저장된다.
• 여러 언어로 문서화에 기여하거나 새로운 번역을 시작하는 방법에 대한 자세한 내용은 현지화를 참고한다.

시작하기 전에

CNCF CLA 서명

모든 쿠버네티스 기여자는 반드시 기여자 가이드를 읽고 기여자 라이선스 계약(CLA)에 서명해야 한다.

CLA에 서명하지 않은 기여자의 풀 리퀘스트(pull request)는 자동 테스트에 실패한다. 제공한 이름과 이메일은 git config 에 있는 것과 일치해야 하며, git 이름과 이메일은 CNCF CLA에 사용된 것과 일치해야 한다.

사용할 Git 브랜치를 선택한다

풀 리퀘스트를 열 때는, 작업의 기반이 되는 브랜치를 미리 알아야 한다.

어떤 브랜치를 선택해야 할지 잘 모르는 경우 슬랙의 #sig-docs 에 문의한다.

참고: 풀 리퀘스트를 이미 제출했는데 기본 브랜치가 잘못되었다는 것을 알게 되면, 제출자(제출자인 여러분만)가 이를 변경할 수 있다.

PR 당 언어

PR 당 하나의 언어로 풀 리퀘스트를 제한한다. 여러 언어로 동일한 코드 샘플을 동일하게 변경해야 하는 경우 각 언어마다 별도의 PR을 연다.

기여자를 위한 도구들

kubernetes/website 리포지터리의 문서 기여자를 위한 도구 디렉터리에는 기여 여정이 좀 더 순조롭게 진행되도록 도와주는 도구들이 포함되어 있다.

2.2 - 풀 리퀘스트 열기

참고: 코드 개발자: 향후 쿠버네티스 릴리스의 새로운 기능을 문서화하는 경우, 새 기능 문서화를 참고한다.

새 콘텐츠 페이지를 기여하거나 기존 콘텐츠 페이지를 개선하려면, 풀 리퀘스트(PR)를 연다. 시작하기 전에 섹션의 모든 요구 사항을 준수해야 한다.

변경 사항이 작거나, git에 익숙하지 않은 경우, GitHub을 사용하여 변경하기를 읽고 페이지를 편집하는 방법을 알아보자.

변경 사항이 많으면, 로컬 포크에서 작업하기를 읽고 컴퓨터에서 로컬로 변경하는 방법을 배운다.

GitHub을 사용하여 변경하기

git 워크플로에 익숙하지 않은 경우, 풀 리퀘스트를 여는 쉬운 방법이 있다.

1. 이슈가 있는 페이지에서, 오른쪽 상단에 있는 연필 아이콘을 선택한다. 페이지 하단으로 스크롤 하여 페이지 편집하기 를 선택할 수도 있다.

2. GitHub 마크다운 편집기에서 수정한다.

3. 편집기 아래에서, Propose file change 양식을 작성한다. 첫 번째 필드에서, 커밋 메시지 제목을 지정한다. 두 번째 필드에는, 설명을 제공한다.

   참고: 커밋 메시지에 GitHub 키워드를 사용하지 않는다. 나중에 풀 리퀘스트 설명에 추가할 수 있다.

4. Propose file change 를 선택한다.

5. Create pull requests 를 선택한다.

6. Open a pull request 화면이 나타난다. 양식을 작성한다.

   • 풀 리퀘스트의 Subject 필드는 기본적으로 커밋의 요약으로 설정한다. 필요한 경우 변경할 수 있다.
   • Body 는 만약 내용이 있다면, 확장된 커밋 메시지를 포함한다. 그리고 일부 템플릿 텍스트를 포함한다. 템플릿 텍스트에 필요한 세부 정보를 추가한 다음, 추가 템플릿 텍스트를 삭제한다.
   • Allow edits from maintainers 체크박스는 선택된 상태로 둔다.

   참고: PR 설명은 리뷰어가 변경 사항을 이해하는 데 유용한 방법이다. 자세한 내용은 PR 열기를 참고한다.

7. Create pull request 를 선택한다.

GitHub에서 피드백 해결

풀 리퀘스트를 병합하기 전에, 쿠버네티스 커뮤니티 회원은 이를 리뷰하고 승인한다. k8s-ci-robot 은 이 페이지에 나와있는 가까운 멤버에게 리뷰를 제안한다. 특정한 사람을 염두에 두고 있다면, GitHub 사용자 이름을 코멘트로 남긴다.

리뷰어가 변경을 요청하는 경우, 다음과 같이 한다.

1. Files changed 탭으로 이동 한다.
2. 풀 리퀘스트에 의해 변경된 파일에서 연필(편집) 아이콘을 선택한다.
3. 요청된 변경에 대한 수정을 한다.
4. 변경 사항을 커밋한다.

리뷰어를 기다리고 있는 경우, 7일마다 한 번씩 연락한다. 슬랙 채널 #sig-docs 에 메시지를 게시할 수도 있다.

리뷰가 완료되면, 리뷰어가 PR을 병합하고 몇 분 후에 변경 사항이 적용된다.

로컬 포크에서 작업하기

git에 익숙하거나, 변경 사항이 몇 줄보다 클 경우, 로컬 포크로 작업한다.

컴퓨터에 git이 설치되어 있는지 확인한다. git UI 애플리케이션을 사용할 수도 있다.

kubernetes/website 리포지터리 포크하기

1. kubernetes/website 리포지터리로 이동한다.
2. Fork 를 선택한다.

로컬 클론 생성 및 업스트림 설정

3. 터미널 창에서, 포크를 클론하고 Docsy Hugo 테마를 업데이트한다.

   git clone git@github.com/<github_username>/website
   cd website
   git submodule update --init --recursive --depth 1
   

4. 새 website 디렉터리로 이동한다. kubernetes/website 리포지터리를 upstream 원격으로 설정한다.

   cd website
   
   git remote add upstream https://github.com/kubernetes/website.git
   

5. origin 과 upstream 리포지터리를 확인한다.

   git remote -v
   

   출력은 다음과 비슷하다.

   origin	git@github.com:<github_username>/website.git (fetch)
   origin	git@github.com:<github_username>/website.git (push)
   upstream	https://github.com/kubernetes/website (fetch)
   upstream	https://github.com/kubernetes/website (push)
   

6. 포크의 origin/master 와 kubernetes/website 의 upstream/master 에서 커밋을 가져온다.

   git fetch origin
   git fetch upstream
   

   이를 통해 변경을 시작하기 전에 로컬 리포지터리가 최신 상태인지 확인한다.

   참고: 이 워크플로는 쿠버네티스 커뮤니티 GitHub 워크플로와 다르다. 포크에 업데이트를 푸시하기 전에 로컬의 master 복사본을 upstream/master 와 병합할 필요가 없다.

브랜치 만들기

1. 작업할 브랜치 기반을 결정한다.

• 기존 콘텐츠를 개선하려면, upstream/master 를 사용한다.

• 기존 기능에 대한 새로운 콘텐츠를 작성하려면, upstream/master 를 사용한다.

• 현지화된 콘텐츠의 경우, 현지화 규칙을 사용한다. 자세한 내용은 쿠버네티스 문서 현지화를 참고한다.

• 다가오는 쿠버네티스 릴리스의 새로운 기능에 대해서는 기능 브랜치(feature branch)를 사용한다. 자세한 정보는 릴리스 문서화를 참고한다.

• 콘텐츠 재구성과 같이 여러 SIG Docs 기여자들이 협업하는 장기적인 작업에는, 해당 작업을 위해 작성된 특정 기능 브랜치를 사용한다.

  브랜치 선택에 도움이 필요하면, 슬랙 채널 #sig-docs 에 문의한다.

2. 1단계에서 식별된 브랜치를 기반으로 새 브랜치를 작성한다. 이 예에서는 기본 브랜치가 upstream/master 라고 가정한다.

   git checkout -b <my_new_branch> upstream/master
   

3. 텍스트 편집기를 사용하여 변경한다.

언제든지, git status 명령을 사용하여 변경한 파일을 본다.

변경 사항 커밋

풀 리퀘스트를 제출할 준비가 되면, 변경 사항을 커밋한다.

1. 로컬 리포지터리에서 커밋해야 할 파일을 확인한다.

   git status
   

   출력은 다음과 비슷하다.

   On branch <my_new_branch>
   Your branch is up to date with 'origin/<my_new_branch>'.
   
   Changes not staged for commit:
   (use "git add <file>..." to update what will be committed)
   (use "git checkout -- <file>..." to discard changes in working directory)
   
   modified:   content/en/docs/contribute/new-content/contributing-content.md
   
   no changes added to commit (use "git add" and/or "git commit -a")
   

2. Changes not staged for commit 에 나열된 파일을 커밋에 추가한다.

   git add <your_file_name>
   

   각 파일에 대해 이 작업을 반복한다.

3. 모든 파일을 추가한 후, 커밋을 생성한다.

   git commit -m "Your commit message"
   

   참고: 커밋 메시지에 GitHub 키워드를 사용하지 말자. 나중에 풀 리퀘스트 설명에 추가할 수 있다.

4. 로컬 브랜치와 새로운 커밋을 원격 포크로 푸시한다.

   git push origin <my_new_branch>
   

로컬에서 변경 사항 미리보기

변경 사항을 푸시하거나 풀 리퀘스트를 열기 전에 변경 사항을 로컬에서 미리 보는 것이 좋다. 미리보기를 사용하면 빌드 오류나 마크다운 형식 문제를 알아낼 수 있다.

website의 컨테이너 이미지를 만들거나 Hugo를 로컬에서 실행할 수 있다. 도커 이미지 빌드는 느리지만 Hugo 단축코드를 표시하므로, 디버깅에 유용할 수 있다.

• Hugo 컨테이너
• Hugo 커맨드 라인

포크에서 kubernetes/website로 풀 리퀘스트 열기

1. 웹 브라우저에서 kubernetes/website 리포지터리로 이동한다.

2. New Pull Request 를 선택한다.

3. compare across forks 를 선택한다.

4. head repository 드롭다운 메뉴에서, 포크를 선택한다.

5. compare 드롭다운 메뉴에서, 브랜치를 선택한다.

6. Create Pull Request 를 선택한다.

7. 풀 리퀘스트에 대한 설명을 추가한다.

   • Title(50자 이하): 변경 사항에 대한 의도를 요약한다.
   • Description: 변경 사항을 자세히 설명한다.
     • 관련된 GitHub 이슈가 있는 경우, Fixes #12345 또는 Closes #12345 를 설명에 포함한다. 이렇게 하면 GitHub의 자동화 기능이 PR을 병합한 후 언급된 이슈를 닫는다. 다른 관련된 PR이 있는 경우, 이들 PR도 연결한다.
     • 구체적인 내용에 대한 조언이 필요한 경우, 원하는 질문을 리뷰어가 생각해볼 수 있도록 설명에 포함한다.

8. Create pull request 버튼을 선택한다.

축하한다! 여러분의 풀 리퀘스트가 풀 리퀘스트에 열렸다.

PR을 연 후, GitHub는 자동 테스트를 실행하고 Netlify를 사용하여 미리보기를 배포하려고 시도한다.

• Netlify 빌드가 실패하면, 자세한 정보를 위해 Details 를 선택한다.
• Netlify 빌드가 성공하면, Details 를 선택하면 변경 사항이 적용된 쿠버네티스 website의 커밋하기 직전의 버전(staged version)이 열린다. 리뷰어가 변경 사항을 확인하는 방법이다.

또한 GitHub는 리뷰어에게 도움을 주기 위해 PR에 레이블을 자동으로 할당한다. 필요한 경우 직접 추가할 수도 있다. 자세한 내용은 이슈 레이블 추가와 제거를 참고한다.

로컬에서 피드백 해결

1. 변경한 후, 이전 커밋을 수정한다.

   git commit -a --amend
   

   • -a: 모든 변경 사항을 커밋
   • --amend: 새로운 커밋을 만들지 않고, 이전 커밋을 수정한다.

2. 필요한 경우 커밋 메시지를 업데이트한다.

3. git push origin <my_new_branch> 를 사용해서 변경 사항을 푸시하고 Netlify 테스트를 다시 실행한다.

   참고: 수정하는 대신 git commit -m 을 사용하는 경우, 병합하기 전에 커밋을 스쿼시해야 한다.

리뷰어의 변경

때때로 리뷰어가 여러분의 풀 리퀘스트를 커밋한다. 다른 변경을 하기 전에, 커밋을 가져온다.

1. 원격 포크에서 커밋을 가져오고 작업 브랜치를 리베이스한다.

   git fetch origin
   git rebase origin/<your-branch-name>
   

2. 리베이스한 후, 포크에 새로운 변경 사항을 강제로 푸시한다.

   git push --force-with-lease origin <your-branch-name>
   

충돌 병합 및 리베이스

참고: 자세한 내용은 Git 브랜치 - 기본 브랜치와 병합, 고급 병합을 참조하거나, 슬랙 채널 #sig-docs 에서 도움을 요청한다.

다른 기여자가 다른 PR에서 동일한 파일에 대한 변경 사항을 커밋하면, 병합 충돌이 발생할 수 있다. PR의 모든 병합 충돌을 해결해야 한다.

1. 포크를 업데이트하고 로컬 브랜치를 리베이스한다.

   git fetch origin
   git rebase origin/<your-branch-name>
   

   그런 다음 포크에 변경 사항을 강제로 푸시한다.

   git push --force-with-lease origin <your-branch-name>
   

2. kubernetes/website 의 upstream/master 에 대한 변경 사항을 가져오고 브랜치를 리베이스한다.

   git fetch upstream
   git rebase upstream/master
   

3. 리베이스의 결과를 검사한다.

   git status
   

이 명령의 결과에 여러 파일이 충돌된 것으로 표시된다.

4. 충돌하는 각 파일을 열고 충돌 마커(>>>,<<< 그리고 ===)를 찾는다. 충돌을 해결하고 충돌 마커를 삭제한다.

   참고: 자세한 내용은 충돌이 표시되는 방법을 참고한다.

5. 변경 세트에 파일을 추가한다.

   git add <filename>
   

6. 리베이스를 계속한다.

   git rebase --continue
   

7. 필요에 따라 2단계에서 5단계를 반복한다.

   모든 커밋을 적용한 후, git status 명령은 리베이스가 완료되었음을 나타낸다.

8. 브랜치를 포크에 강제로 푸시한다.

   git push --force-with-lease origin <your-branch-name>
   

   풀 리퀘스트에 더 이상 충돌이 표시되지 않는다.

커밋 스쿼시하기

참고: 자세한 내용은 Git 도구 - 히스토리 다시 쓰기를 참고하거나, 슬랙 채널 #sig-docs 에서 도움을 요청한다.

PR에 여러 커밋이 있는 경우, PR을 병합하기 전에 해당 커밋을 단일 커밋으로 스쿼시해야 한다. PR의 Commits 탭에서 또는 git log 명령을 로컬에서 실행하여 커밋 수를 확인할 수 있다.

참고: 여기서는 vim 을 커맨드 라인 텍스트 편집기로 사용하는 것을 가정한다.

1. 대화식 리베이스를 시작한다.

   git rebase -i HEAD~<number_of_commits_in_branch>
   

   커밋을 스쿼시하는 것은 일종의 리베이스이다. git의 -i 스위치는 리베이스를 대화형으로 할 수 있게 한다. HEAD~<number_of_commits_in_branch> 는 리베이스를 위해 살펴볼 커밋 수를 나타낸다.

   출력은 다음과 비슷하다.

   pick d875112ca Original commit
   pick 4fa167b80 Address feedback 1
   pick 7d54e15ee Address feedback 2
   
   # 3d18sf680..7d54e15ee 를 3d183f680 으로 리베이스한다 (3개 명령)
   
   ...
   
   # 이 행들은 순서를 바꿀 수 있다. 이들은 위에서 아래로 실행된다.
   

   출력의 첫 번째 섹션에는 리베이스의 커밋이 나열된다. 두 번째 섹션에는 각 커밋에 대한 옵션이 나열되어 있다. pick 단어를 바꾸면 리베이스가 완료되었을 때 커밋 상태가 변경된다.

   리베이스를 하는 목적인 squash 와 pick 에 집중한다.

   참고: 자세한 내용은 대화식 모드를 참고한다.

2. 파일 편집을 시작한다.

   다음의 원본 텍스트를 변경한다.

   pick d875112ca Original commit
   pick 4fa167b80 Address feedback 1
   pick 7d54e15ee Address feedback 2
   

   아래와 같이 변경한다.

   pick d875112ca Original commit
   squash 4fa167b80 Address feedback 1
   squash 7d54e15ee Address feedback 2
   

   이것은 커밋 4fa167b80 Address feedback 1 과 7d54e15ee Address feedback 2 를 d875112ca Original commit 으로 스쿼시한다. 타임라인의 일부로 d875112ca Original commit 만 남긴다.

3. 파일을 저장하고 종료한다.

4. 스쿼시된 커밋을 푸시한다.

   git push --force-with-lease origin <branch_name>
   

다른 리포지터리에 기여하기

쿠버네티스 프로젝트에는 50개 이상의 리포지터리가 포함되어 있다. 이러한 리포지터리에는 사용자용 도움말 텍스트, 오류 메시지, API 레퍼런스 또는 코드 주석과 같은 문서가 포함되어 있다.

개선하려는 텍스트가 보이면, GitHub을 사용하여 쿠버네티스 조직의 모든 리포지터리를 검색한다. 이를 통해 어디에 이슈나 PR을 제출할지를 파악할 수 있다.

각 리포지터리에는 고유한 프로세스와 절차가 있다. 여러분이 이슈를 제기하거나 PR을 제출하기 전에, 그 리포지터리의 README.md, CONTRIBUTING.md 그리고 code-of-conduct.md(만약 이들 문서가 있다면)를 읽어본다.

대부분의 리포지터리에는 이슈와 PR 템플릿이 사용된다. 팀의 프로세스에 대한 느낌을 얻으려면 열린 이슈와 PR을 살펴보자. 이슈나 PR을 제출할 때 가능한 한 상세하게 템플릿의 내용을 작성한다.

다음 내용

• 리뷰 프로세스에 대한 자세한 내용은 리뷰하기를 읽어본다.

3 - 변경 사항 리뷰하기

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

3.1 - 풀 리퀘스트 리뷰

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

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

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

• 적합한 코멘트를 남길 수 있도록 콘텐츠 가이드와 스타일 가이드를 읽는다.
• 쿠버네티스 문서화 커뮤니티의 다양한 역할과 책임을 이해한다.

시작하기 전에

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

• CNCF 행동 강령을 읽고 항상 준수한다.
• 정중하고, 사려 깊고, 도움이 되자.
• PR의 긍정적인 측면과 변화에 대한 의견을 남긴다.
• 당신의 리뷰를 어떻게 받아들일지에 대해 공감하고 주의한다.
• 좋은 의도를 가지고 명확한 질문을 한다.
• 숙련된 기여자인 경우, 작업에 광범위한 변경이 필요한 새 기여자와 쌍을 이루어 리뷰해 본다.

리뷰 과정

일반적으로, 영어로 콘텐츠와 스타일에 대한 풀 리퀘스트를 리뷰한다.

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

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

   • cncf-cla: yes(권장): CLA에 서명하지 않은 기여자가 제출한 PR은 병합할 수 없다. 자세한 내용은 CLA 서명을 참고한다.
   • language/en(권장): 영어 문서에 대한 PR 전용 필터이다.
   • size/<size>: 특정 크기의 PR을 필터링한다. 새로 시작하는 사람이라면, 더 작은 PR로 시작한다.

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

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

   • PR 설명을 통해 변경 사항을 이해하고, 연결된 이슈 읽기
   • 다른 리뷰어의 의견 읽기
   • Files changed 탭을 클릭하여 변경된 파일과 행 보기
   • Conversation 탭의 맨 아래에 있는 PR의 빌드 확인 섹션으로 스크롤하여 deploy/netlify 행의 Details 링크를 클릭하고 Netlify 미리보기 빌드의 변경 사항을 확인

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

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

리뷰 체크리스트

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

언어와 문법

• 언어나 문법에 명백한 오류가 있는가? 무언가를 표현하는 더 좋은 방법이 있는가?
• 더 간단한 단어로 대체될 수 있는 복잡하거나 오래된 단어가 있는가?
• 비 차별적 대안으로 대체될 수 있는 단어, 용어 또는 문구가 있는가?
• 단어 선택과 대소문자는 스타일 가이드를 따르는가?
• 더 짧고 간결하게 만들 수 있는 긴 문장이 있는가?
• 목록이나 표로 더 잘 표현할 수 있는 긴 단락이 있는가?

콘텐츠

• 쿠버네티스 사이트의 다른 곳에도 비슷한 콘텐츠가 있는가?
• 콘텐츠가 오프-사이트, 개별 업체, 또는 공개되지 않은 소스 문서에 과도하게 링크되는가?

웹 사이트

• 이 PR이 페이지 제목, slug/alias 또는 앵커(anchor) 링크를 변경 또는 제거하는가? 그렇다면, 이 PR의 결과로 끊어진 링크가 있는가? slug를 변경 없이 페이지 제목을 변경하는 등의 다른 옵션이 있는가?
• PR이 새로운 페이지를 소개하는가? 그렇다면,
  • 페이지가 올바른 페이지 콘텐츠 타입과 연관된 Hugo 단축 코드를 사용하는가?
  • 섹션의 측면 탐색에 페이지가 올바르게 나타나는가?
  • 페이지가 문서 홈 목록에 나타나야 하는가?
• 변경 사항이 Netlify 미리보기에 표시되는가? 목록, 코드 블록, 표, 메모 및 이미지에 특히 주의한다.

기타

오타나 공백과 같은 작은 이슈의 PR인 경우, 코멘트 앞에 nit: 를 추가한다. 이를 통해 문서의 저자는 이슈가 긴급하지 않다는 것을 알 수 있다.

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

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

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

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

PR 리뷰

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

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

• /assign Prow 명령을 사용하여 필요에 따라 특정 리뷰어를 PR에 할당한다. 이는 코드 기여자에게 기술 리뷰를 요청할 때 특히 중요하다.

  참고: 마크다운 파일 맨 위에 있는 헤더의 reviewers 필드를 보고 기술 리뷰를 제공할 수 있는 사람을 확인한다.

• PR이 콘텐츠와 스타일 가이드를 따르는 지 확인한다. 그렇지 않은 경우 가이드의 관련 부분에 작성자를 연결한다.

• 적용이 가능한 경우 GitHub Request Changes 옵션을 사용하여 PR 작성자에게 변경을 제안한다.

• 제안한 사항이 구현된 경우, /approve 또는 /lgtm Prow 명령을 사용하여 GitHub에서 리뷰 상태를 변경한다.

다른 사람의 PR에 커밋

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

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

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

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

• PR 작성자가 브랜치를 https://github.com/kubernetes/website/ 리포지터리로 직접 푸시한 경우, 푸시 접근 권한이 있는 리뷰어만 다른 사용자의 PR에 커밋할 수 있다.

  참고: 다음 번부터는 PR을 열기 전에 작성자가 브랜치를 자신의 포크로 푸시하도록 권장한다.

• PR 작성자가 승인자의 수정을 명시적으로 허용하지 않는다.

리뷰를 위한 Prow 명령

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

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

PR에서 사용할 수 있는 명령의 전체 목록을 보려면 Prow 명령 레퍼런스를 참고한다.

이슈 심사와 분류

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

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

이슈 심사

1. 이슈 확인

• 이슈가 website 문서에 관한 것인지 확인한다. 질문에 답하거나 리소스에 리포터를 지정하면 일부 이슈를 신속하게 종결할 수 있다. 자세한 내용은 지원 요청 또는 코드 버그 리포트 섹션을 참고한다.
• 이슈가 가치가 있는지 평가한다.
• 이슈의 내용에 실행할 수 있는 세부 사항이 충분하지 않거나 템플릿의 내용이 제대로 작성되지 않은 경우 triage/needs-information 레이블을 추가한다.
• lifecycle/stale 과 triage/needs-information 레이블이 모두 있으면 이슈를 닫는다.

2. 우선순위 레이블을 추가한다(이슈 심사 가이드라인은 우선순위 레이블을 자세히 정의함).

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

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

이슈 레이블 추가와 제거

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

• /<label-to-add> (예: /good-first-issue)
• /<label-category> <label-to-add> (예: /triage needs-information 또는 /language ko)

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

• /remove-<label-to-remove> (예: /remove-help)
• /remove-<label-category> <label-to-remove> (예: /remove-triage needs-information)

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

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

이슈의 lifecycle 레이블

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

특별한 이슈 유형의 처리

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

중복된 이슈

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

깨진 링크 이슈

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

블로그 이슈

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

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

문서에 대한 일부 이슈는 실제로 기본 코드와 관련된 이슈이거나, 튜토리얼과 같은 무언가가 작동하지 않을 때 도움을 요청하는 것이다. 문서와 관련이 없는 이슈의 경우, 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 에서
이슈를 여십시오.

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

4 - 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}-reviewers

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

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

OWNERS 파일과 전문(front-matter)

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

• blunderbuss
• approve

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

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

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

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

병합 작업 방식

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

• 풀 리퀘스트에 lgtm 과 approve 레이블이 있고, hold 레이블이 없고, 모든 테스트를 통과하면 풀 리퀘스트는 자동으로 병합된다.
• 쿠버네티스 조직의 멤버와 SIG Docs 승인자들은 지정된 풀 리퀘스트의 자동 병합을 방지하기 위해 코멘트를 추가할 수 있다(코멘트에 /hold 추가 또는 /lgtm 코멘트 보류).
• 모든 쿠버네티스 멤버는 코멘트에 /lgtm 을 추가해서 lgtm 레이블을 추가할 수 있다.
• SIG Docs 승인자들만이 코멘트에 /approve 를 추가해서 풀 리퀘스트를 병합할 수 있다. 일부 승인자들은 PR Wrangler 또는 SIG Docs 의장과 같은 특정 역할도 수행한다.

다음 내용

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

• 신규 콘텐츠 기여하기
• 콘텐츠 검토하기
• 문서 스타일 가이드

4.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은 초대를 여러분 계정의 기본 이메일 주소로 보낸다.

리뷰어

리뷰어는 열린 풀 리퀘스트를 리뷰할 책임이 있다. 멤버 피드백과는 달리, 여러분은 리뷰어의 피드백을 반드시 해결해야 한다. 리뷰어는 @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 에 추가한다.

1. 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 랭글러에 대해 읽어보기

4.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을 병합하려면 승인을 위한 approve 코멘트를 사용한다. 준비가 되면 PR을 병합한다.
  • 병합하기 전에 PR은 다른 멤버의 /lgtm 코멘트를 받아야 한다.
  • [스타일 지침]을 충족하지 않지만 기술적으로는 정확한 PR은 수락하는 것을 고려한다. 스타일 문제를 해결하는 good first issue 레이블의 새로운 이슈를 올리면 된다.

랭글러를 위해 도움이 되는 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 코멘트를 남긴다.

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

5 - 문서 스타일 개요

이 섹션의 주제는 문서 작성 스타일, 컨텐츠 형식과 구성, 쿠버네티스 문서화에 적합하게 사용자 정의된 Hugo 사용 방법에 대한 가이드를 제공한다.

5.1 - 새로운 주제의 문서 작성

이 페이지는 쿠버네티스 문서에서 새로운 주제를 생성하는 방법을 보여준다.

시작하기 전에

PR 열기에 설명된 대로 쿠버네티스 문서 저장소의 포크(fork)를 생성하자.

페이지 타입 선택

새로운 주제 작성을 준비할 때는, 콘텐츠에 가장 적합한 페이지 타입을 고려하자.

새 페이지 작성

작성하는 각각의 새 페이지에 대해 콘텐츠 타입을 사용하자. 문서 사이트는 새 콘텐츠 페이지를 작성하기 위한 템플리트 또는 Hugo archetypes을 제공한다. 새로운 타입의 페이지를 작성하려면, 작성하려는 파일의 경로로 hugo new 를 실행한다. 예를 들면, 다음과 같다.

hugo new docs/concepts/my-first-concept.md

제목과 파일 이름 선택

검색 엔진에서 찾을 키워드가 있는 제목을 선택하자. 제목에 있는 단어를 하이픈으로 구분하여 사용하는 파일 이름을 만들자. 예를 들어 HTTP 프록시를 사용하여 쿠버네티스 API에 접근 이라는 제목의 문서는 http-proxy-access-api.md라는 이름의 파일을 가진다. "쿠버네티스"가 이미 해당 주제의 URL에 있기 때문에 파일 이름에 "쿠버네티스" 를 넣을 필요가 없다. 예를 들면 다음과 같다.

   /docs/tasks/extend-kubernetes/http-proxy-access-api/

전문에 항목 제목 추가

문서에서 전문 에 title 필드를 입력하자. 전문은 페이지 상단의 3중 점선 사이에 있는 YAML 블록이다. 여기 예시가 있다.

---
title: HTTP 프록시를 사용하여 쿠버네티스 API에 접근
---

디렉터리 선택

페이지 타입에 따라 새로운 파일을 다음 중 하나의 하위 디렉터리에 넣자.

• /content/en/docs/tasks/
• /content/en/docs/tutorials/
• /content/en/docs/concepts/

파일을 기존 하위 디렉터리에 넣거나 새 하위 디렉터리에 넣을 수 있다.

목차에 항목 배치

목차는 문서 소스의 디렉터리 구조를 사용하여 동적으로 작성된다. /content/en/docs/ 아래의 최상위 디렉터리는 최상위 레벨 탐색 기능을 생성하고, 하위 디렉터리는 각각 목차에 항목을 갖는다.

각 하위 디렉터리에는 _index.md 파일이 있으며 이는 해당 하위 디렉터리의 컨텐츠에 대한 "홈" 페이지를 나타낸다. _index.md에는 템플릿이 필요없다. 그것은 하위 디렉터리의 항목에 대한 개요 내용을 포함할 수 있다.

디렉터리의 다른 파일들은 기본적으로 알파벳순으로 정렬된다. 이것은 거의 최적의 순서가 아니다. 하위 디렉터리에서 항목의 상대적 정렬을 제어하려면 가중치: 전문의 키를 정수로 설정하자. 일반적으로 우리는 나중에 항목을 추가하기 위해 10의 배수를 사용한다. 예를 들어 가중치가 10인 항목은 가중치가 20인 항목보다 우선한다.

문서에 코드 포함

문서에 코드를 포함시키려면 마크다운 코드 블록 구문을 사용하여 파일에 코드를 직접 삽입하자. 다음 경우에 권장된다. (전체 목록은 아님)

• 이 코드는 kubectl get deploy mydeployment -o json | jq '.status'와 같은 명령어의 출력을 보여준다.
• 이 코드는 시도해보기에 적절하지 않다. 예를 들어 특정 FlexVolume 구현에 따라 파드를 만들기 위해 YAML 파일을 포함할 수 있다.
• 이 코드의 목적은 더 큰 파일의 일부를 강조하는 것이기 때문에 불완전한 예제다. 예를 들어 몇 가지 이유로 PodSecurityPolicy 를 사용자 정의 방법을 설명할 때 문서 파일에서 직접 짧은 요약 정보를 제공할 수 있다.
• 이 코드는 사용자가 다른 이유로 시도하기 위한 것이 아니다. 예를 들어 kubectl edit 명령을 사용하여 리소스에 새 속성을 추가하는 방법을 설명할 때 추가할 만한 속성을 포함하는 간단한 예를 제공할 수 있다.

다른 파일의 코드 포함

문서에 코드를 포함시키는 또 다른 방법은 새로운 완전한 샘플 파일 (또는 샘플 파일 그룹)을 만든 다음 문서의 샘플을 참조하는 것이다. 일반적이고 재사용 가능하며 독자가 스스로 실행해 볼 수 있도록 하는 샘플 YAML 파일을 포함시키려면 이 방법을 사용하자.

YAML 파일과 같은 새로운 독립형 샘플 파일을 추가할 때 <LANG>/examples/ 의 하위 디렉터리 중 하나에 코드를 배치하자. 여기서 <LANG>은 주제에 관한 언어이다. 문서 파일에서 codenew 단축 코드(shortcode)를 사용하자.

{{< codenew file="<RELPATH>/my-example-yaml>" >}}

여기서 <RELPATH> 는 examples 디렉터리와 관련하여 포함될 파일의 경로이다. 다음 Hugo 단축 코드(shortcode)는 /content/en/examples/pods/storage/gce-volume.yaml 에 있는 YAML 파일을 참조한다.

{{< codenew file="pods/storage/gce-volume.yaml" >}}

참고: 위의 예와 같은 원시 Hugo 단축 코드(shortcode)를 표시하고 Hugo가 해석하지 못하게 하려면 < 문자 바로 다음과 > 문자 앞에 C 스타일 주석을 사용하자. 그 예로서 이 페이지의 코드를 확인하자.

구성 파일에서 API 오브젝트를 작성하는 방법 표시

구성 파일을 기반으로 API 오브젝트를 생성하는 방법을 보여주려면 <LANG>/examples 아래의 하위 디렉터리 중 하나에 구성 파일을 배치하자.

문서에서 이 명령을 띄워보자.

kubectl create -f https://k8s.io/examples/pods/storage/gce-volume.yaml

참고: <LANG>/examples 디렉터리에 새 YAMl 파일을 추가할 때 파일이 <LANG>/examples_test.go 파일에도 포함되어 있는지 확인하자. 웹 사이트의 Travis CI 는 PR이 제출될 때 이 예제를 자동으로 실행하여 모든 예제가 테스트를 통과하도록 한다.

이 기술을 사용하는 문서의 예로 단일 인스턴스 스테이트풀 어플리케이션 실행을 참조하자.

문서에 이미지 추가

이미지 파일을 /images 디렉터리에 넣는다. 기본 이미지 형식은 SVG 이다.

다음 내용

• 페이지 콘텐츠 타입 사용에 대해 알아보기.
• 풀 리퀘스트 작성에 대해 알아보기.

6 - 참조 문서 개요

이 섹션은 쿠버네티스 참조 가이드를 생성하는 방법에 대해 설명한다.

참조 문서화 시스템을 빌드하려면, 다음의 가이드를 참고한다.

• 참조 문서 생성에 대한 퀵스타트 가이드

7 - 고급 기여

이 페이지에서는 당신이 새로운 콘텐츠에 기여하고 다른 사람의 작업을 리뷰하는 방법을 이해한다고 가정한다. 또한 기여하기 위한 더 많은 방법에 대해 배울 준비가 되었다고 가정한다. 이러한 작업 중 일부에는 Git 커맨드 라인 클라이언트와 다른 도구를 사용해야 한다.

개선 제안

SIG Docs 멤버는 개선을 제안할 수 있다.

한 동안 쿠버네티스 문서에 기여한 후에, 스타일 가이드, 컨텐츠 가이드, 문서 작성에 사용되는 툴체인, website 스타일, 풀 리퀘스트 리뷰와 병합 프로세스 또는 문서 작성의 다른 측면을 개선하기 위한 아이디어가 있을 수 있다. 투명성을 극대화하려면, 이러한 유형의 제안을 SIG Docs 회의나 kubernetes-sig-docs 메일링리스트에서 논의해야 한다. 또한, 현재의 작업 방식과 과거의 결정이 왜 획기적인 변경을 제안하기 전에 결정되었는지에 대한 맥락을 이해하는 데 실제로 도움이 될 수 있다. 현재의 문서 작업이 어떻게 진행되는지에 대한 질문의 답변을 얻는 가장 빠른 방법은 kubernetes.slack.com의 #sig-docs 슬랙 채널에 문의하는 것이다.

토론이 진행되고 원하는 결과에 SIG가 동의한 후에는, 제안한 변경 사항과 가장 적합한 방식으로 작업할 수 있다. 예를 들어, 스타일 가이드나 website의 기능을 업데이트하려면, sig-testing과 함께 작업이 필요할 수 있는 문서 테스트와 관련된 변경에 대해 풀 리퀘스트를 열어야 할 수 있다.

쿠버네티스 릴리스를 위한 문서 조정

SIG Docs 승인자는 쿠버네티스 릴리스에 대한 문서를 조정할 수 있다.

각 쿠버네티스 릴리스는 sig-release SIG(Special Interest Group)에 참여하는 사람들의 팀에 의해 조정된다. 특정 릴리스에 대한 릴리스 팀의 다른 구성원에는 전체 릴리스 리드와 sig-testing 및 기타 담당자가 포함된다. 쿠버네티스 릴리스 프로세스에 대한 자세한 내용은 https://github.com/kubernetes/sig-release를 참고한다.

특정 릴리스의 SIG Docs 담당자는 다음 작업을 조정한다.

• 문서에 영향을 미치는 새로운 기능이나 변경된 기능이 있는지 기능-추적 스프레드시트를 모니터링한다. 특정 기능에 대한 문서가 릴리스를 위해 준비가 되지 않은 경우, 해당 기능이 릴리스 되지 않을 수 있다.
• sig-release 미팅에 정기적으로 참석하고 릴리스에 대한 문서의 상태를 업데이트한다.
• 기능 구현을 담당하는 SIG가 작성한 기능 문서를 리뷰하고 교정한다.
• 릴리스 관련 풀 리퀘스트를 병합하고 릴리스에 대한 Git 기능 브랜치를 유지 보수한다.
• 앞으로 이 역할을 수행하는 방법을 배우려는 다른 SIG Docs 기여자들을 멘토링한다. 이것을 "섀도잉"이라고 한다.
• 릴리스에 대한 산출물이 공개될 때 릴리스와 관련된 문서 변경 사항을 공개한다.

릴리스 조정은 일반적으로 3-4개월의 책임이며, SIG Docs 승인자 사이에서 의무가 순환된다.

새로운 기여자 홍보대사로 봉사

SIG Docs 승인자는 새로운 기여자 홍보대사로 활동할 수 있다.

새로운 기여자 홍보대사는 SIG-Docs에 기여한 새 기여자를 환영하고, 새 기여자에게 PR을 제안하고, 첫 몇 번의 PR 제출을 통해 새 기여자를 멘토링한다.

새로운 기여자 홍보대사의 책임은 다음과 같다.

• #sig-docs 슬랙 채널에서 새로운 기여자의 질문을 모니터링한다.
• PR 랭글러와 협력하여 새로운 기여자에게 좋은 첫 이슈를 파악한다.
• 문서 리포지터리에 대한 처음 몇 번의 PR을 통해 새로운 기여자를 멘토링한다.
• 새로운 기여자가 쿠버네티스 멤버가 되기 위해 필요한 보다 복잡한 PR을 작성하도록 지원한다.
• 쿠버네티스 멤버 가입을 위해 기여자를 후원한다.

현재 새로운 기여자 홍보대사는 각 SIG-Docs 회의와 쿠버네티스 #sig-docs 채널에서 발표된다.

새로운 기여자 후원

SIG Docs 리뷰어는 새로운 기여자를 후원할 수 있다.

새로운 기여자가 하나 이상의 쿠버네티스 리포지터리에 5개의 실질적인 풀 리퀘스트를 성공적으로 제출한 후에는 쿠버네티스 조직의 멤버십을 신청할 수 있다. 기여자의 멤버십은 이미 리뷰어인 두 명의 스폰서가 후원해야 한다.

새로운 문서 기여자는 쿠버네티스 슬랙 인스턴스의 #sig-docs 채널이나 SIG Docs 메일링리스트에서 스폰서를 요청할 수 있다. 신청자의 작업에 대해 확신이 있다면, 리뷰어는 신청자를 후원한다. 신청자가 멤버십 신청서를 제출할 때, 신청서에 "+1"로 코멘트를 남기고 신청자가 쿠버네티스 조직의 멤버십에 적합한 이유에 대한 세부 정보를 포함한다.

SIG 공동 의장으로 봉사

SIG Docs 승인자는 SIG Docs의 공동 의장 역할을 할 수 있다.

전제 조건

승인자는 공동 의장이 되려면 다음의 요구 사항을 충족해야 한다.

• 6개월 이상 SIG Docs 승인자로 활동한다.
• 쿠버네티스 문서 릴리스 주도 또는 두 개의 릴리스에서 섀도잉을 수행한다.
• SIG Docs 워크플로와 툴링을 이해한다(git, Hugo, 현지화, 블로그 하위 프로젝트).
• k/org의 팀, k/community의 프로세스, k/test-infra의 플러그인 및 SIG 아키텍처의 역할을 포함하여 다른 쿠버네티스 SIG와 리포지터리가 SIG Docs 워크플로에 미치는 영향을 이해한다.
• 최소 6개월 동안 일주일에 5시간 이상(대부분 더)을 역할에 책임진다.

책임

공동 의장의 역할은 서비스 중 하나이다. 공동 의장은 기여자 역량 확보, 프로세스와 정책 처리, 회의 예약과 진행, PR 랭글러 스케줄링, 쿠버네티스 커뮤니티의 문서에 대한 지지, 쿠버네티스 릴리스 주기에서 성공적으로 문서화되는지 확인하고, SIG Docs를 효과적인 우선순위에 놓이도록 집중한다.

다음과 같은 책임을 가진다.

• SIG Docs가 우수한 문서화를 통해 개발자의 행복을 극대화하는 데 집중한다.
• 스스로가 커뮤니티 행동 강령을 준수하여 예를 보이고, SIG 멤버들이 지킬 수 있도록 책임을 진다.
• 기여에 대한 새로운 지침을 확인하여 SIG에 대한 모범 사례를 배우고 설정한다.
• SIG 회의를 예약하고 진행한다. 주간 상태 업데이트, 브랜치별 회고/기획 세션과 필요에 따라 그 외 세션을 진행한다.
• KubeCon 이벤트 및 기타 컨퍼런스에서 문서 스프린트를 스케줄링하고 진행한다.
• CNCF와 플래티넘 파트너인 Google, Oracle, Azure, IBM 및 Huawei를 통해 SIG Docs를 대신하여 채용과 지지를 보낸다.
• SIG를 원활하게 운영한다.

효과적인 회의 운영

효과적으로 회의를 예약하고 진행하기 위해, 이 지침은 수행할 작업, 수행 방법과 이유를 보여준다.

커뮤니티 행동 강령을 지킨다.

• 정중함을 유지하고, 포괄적인 언어로, 정중하고 포괄적인 토론을 한다.

명확한 안건을 설정한다.

• 주제의 명확한 안건을 설정한다.
• 안건을 미리 게시한다.

주간 회의의 경우, 지난 주 회의록을 회의록의 "지난 회의" 섹션에 복사하여 붙여 넣는다.

정확한 회의록에 대해 공동 작업한다.

• 회의의 토론 내용을 기록한다.
• 회의록 작성자의 역할을 위임한다.

조치 항목을 명확하고 정확하게 지정한다.

• 조치 항목, 조치 항목에 할당된 멤버 그리고 예상 완료 날짜를 기록한다.

필요에 따라 완급을 조절한다.

• 토론이 안건에서 벗어난 경우, 참가자의 초점을 현재의 주제로 다시 맞춘다.
• 토론에 집중하고 사람들의 시간을 존중하면서 다양한 토론 스타일을 위한 공간을 확보한다.

사람들의 시간을 존중한다.

정시에 회의를 시작하고 끝낸다.

줌(Zoom)을 효과적으로 사용한다.

• 쿠버네티스에 대한 줌 가이드라인에 익숙해진다.
• 호스트 키를 입력하여 로그인할 때 호스트 역할을 선택한다.

줌에서 회의 녹화

녹화를 시작할 준비가 되면, Record to Cloud를 클릭한다.

녹화를 중지하려면, Stop을 클릭한다.

비디오가 자동으로 유튜브에 업로드된다.

8 - 쿠버네티스 문서 한글화 가이드

쿠버네티스 문서 한글화를 위한 가이드

팀 마일스톤 관리

쿠버네티스 문서 한글화팀은 커뮤니티의 현지화 가이드에 따라 한글화를 위한 팀 마일스톤과 개발 브랜치를 관리한다. 본 섹션은 한글화팀의 팀 마일스톤 관리에 특화된 내용을 다룬다.

한글화팀은 master 브랜치에서 분기한 개발 브랜치를 사용한다. 개발 브랜치 이름은 다음과 같은 구조를 갖는다.

dev-<소스 버전>-ko.<팀 마일스톤>

개발 브랜치는 약 2주에서 3주 사이의 팀 마일스톤 기간 동안 공동의 작업을 위해 사용되며, 팀 마일스톤이 종료될 때 원 브랜치로 병합(merge)된다.

업스트림(upstream)의 릴리스 주기(약 3개월)에 따라 다음 버전으로 마일스톤을 변경하는 시점에는 일시적으로 release-<소스 버전> 브랜치를 원 브랜치로 사용하는 개발 브랜치를 추가로 운영한다.

한글화팀의 정기 화상 회의 일정과 팀 마일스톤 주기는 대체로 일치하며, 정기 회의를 통해 팀 마일스톤마다 PR 랭글러(wrangler)를 지정한다.

한글화팀의 PR 랭글러가 갖는 의무는 업스트림의 PR 랭글러가 갖는 의무와 유사하다. 단, 업스트림의 PR 랭글러와는 달리 승인자가 아니어도 팀 마일스톤의 PR 랭글러가 될 수 있다. 그래서, 보다 상위 권한이 필요한 업무가 발생한 경우, PR 랭글러는 해당 권한을 가진 한글화팀 멤버에게 처리를 요청한다.

업스트림의 PR 랭글러에게 유용한 GitHub 쿼리를 기반으로 작성한, 한글화팀의 PR 랭글러에게 유용한 쿼리를 아래에 나열한다.

• CLA 서명 없음, 병합할 수 없음
• LGTM 필요
• LGTM 보유, 문서 승인 필요
• 퀵윈(Quick Wins)

팀 마일스톤 일정과 PR 랭글러는 커뮤니티 슬랙 내 #kubernetes-docs-ko 채널에 공지된다.

문체 가이드

높임말

평어체 사용을 원칙으로 하나, 일부 페이지(예: https://kubernetes.io/ko)에 한해 예외적으로 높임말을 사용한다.

명령형

어떤 일을 하도록 청자에게 요구하는 명령형 표현은 간결하고 부드러운 표현으로 정확한 의미를 전달하기 위해 어떤 일을 함께 하기를 요청하는 청유형 또는 객관적으로 진술하는 평어체로 번역한다.

번역체 지양

우리글로서 자연스럽고 무리가 없도록 번역한다.

문서 코딩 가이드

가로폭은 원문을 따름

유지보수의 편의를 위해서 원문의 가로폭을 따른다.

즉, 원문이 한 문단을 줄바꿈하지 않고 한 행에 길게 기술했다면 한글화 시에도 한 행에 길게 기술하고, 원문이 한 문단을 줄바꿈해서 여러 행으로 기술한 경우에는 한글화 시에도 가로폭을 원문과 비슷하게 유지한다.

리뷰어 삭제

때때로 원문의 코드 상단에 리뷰어가 명시되어 있는 경우가 있다. 일반적으로 원문 페이지의 리뷰어가 한글화 된 페이지를 리뷰하기 어려우므로 리소스 메타데이터에서 리뷰어 관련 코드를 삭제한다.

아래는 리뷰어 관련 코드를 삭제하는 예시를 보여준다.

- reviews:
- - reviewer1
- - reviewer
- title: Kubernetes Components
+
+
+
+ title: 쿠버네티스 컴포넌트
content_type: concept
weight: 10

용어 한글화 가이드

용어 한글화의 일반적 방침

영문 용어를 한글화할 때는 다음의 우선 순위를 따르나, 자연스럽지 않은 용어를 무리하게 선택하지는 않는다.

• 한글 단어
  • 순 우리말 단어
  • 한자어 (예: 운영 체제), 외래어 (예: 쿠버네티스, 파드)
• 한영 병기 (예: 훅(hook))
• 영어 단어 (예: Kubelet)

단, 자연스러움을 판단하는 기준은 주관적이므로 한글화 용어집을 준용하고 기존에 번역된 문서를 참고한다.

참고: 한영 병기는 페이지 내에서 해당 용어가 처음 사용될 때, 1회 적용하고 이후에는 한글만 표기한다. 그러나 필요(예: 자연스러움, 명확성 향상 등)에 따라 추가적인 한영 병기를 허용한다. 한영 병기의 대상에는 제목도 포함된다.

API 오브젝트 용어 한글화 방침

일반적으로 kubectl api-resources 결과의 kind 에 해당하는 API 오브젝트는 국립국어원 외래어 표기법에 따라 한글로 표기하고 영문을 병기한다. 예를 들면 다음과 같다.

kind 에 속하는 API 오브젝트 중에서도 일부는 표현의 간결함을 위해 한영병기를 하지 않는 등의 예외가 있으며, 예외에 대해서는 한글화 용어집에 등록된 방식을 준용한다. 예를 들면 다음과 같다.

kind 에 속하지 않는 API 오브젝트는, 한글화 용어집에 등록된 용어인 경우를 제외하고, 모두 원문 그대로 표기한다. 예를 들면 다음과 같다.

참고: 단, API 오브젝트 한글화 원칙에 예외가 있을 수 있으며, 이 경우에는 가능한 한글화 용어집을 준용한다. (예를 들면, Horizontal Pod Autoscaler 는 API 오브젝트에 대해 외래어 표기법을 적용하지 않고 원문 그대로 표기한다.)

참고: 원문에서는 API 오브젝트를 camelCase(예: configMap)로 표기하는 것을 가이드하고 있다. 그러나 한글에는 대소문자 구분이 없으므로 이를 띄어쓰기 없이 붙여서 처리한다. (예: configMap -> 컨피그맵, config Map -> 컨피그맵)

참고: API 오브젝트의 필드 이름, 파일 이름, 경로와 같은 내용은 독자가 구성 파일이나 커맨드라인에서 그대로 사용할 가능성이 높으므로 한글로 옮기지 않고 원문을 유지한다. 단, 주석에 포함된 내용은 한글로 옮길 수 있다.

기능 게이트(feature gate) 한글화 방침

쿠버네티스의 기능 게이트를 의미하는 용어는 한글화하지 않고 원문 형태를 유지한다.

기능 게이트의 예시는 다음과 같다.

• Accelerators
• AdvancedAuditing
• AffinityInAnnotations
• AllowExtTrafficLocalEndpoints
• ...

전체 기능 게이트 목록은 여기를 참고한다.

참고: 단, 해당 원칙에는 예외가 있을 수 있으며, 이 경우에는 가능한 한글화 용어집을 준용한다.

참고: 기능 게이트는 쿠버네티스 버전에 따라 변경될 수 있으므로, 쿠버네티스 및 쿠버네티스 문서의 버전에 맞는 기능 게이트 목록을 적용하여 한글화를 진행한다.

한글화 용어집 정보

쿠버네티스 한글화 용어집은 한글화된 쿠버네티스 문서의 일관성을 위해서 각 영문 용어에 대한 한글화 방법을 제시한다. 한글화 용어집에 포함된 용어는 쿠버네티스 문서 한글화팀 회의를 통해 결정되었으며, 본 문서에 대한 ISSUE 및 PR을 통해서 개선한다.

한글화 용어집 개선 가이드

한글화 용어집의 개선(추가, 수정, 삭제 등)을 위한 과정은 다음과 같다.

1. 컨트리뷰터가 개선이 필요한 용어을 파악하면, ISSUE를 생성하여 개선 필요성을 공유하거나 master 브랜치에 PR을 생성하여 개선된 용어를 제안한다.

2. 개선 제안에 대한 논의는 ISSUE 및 PR을 통해서 이루어지며, 한글화팀 회의를 통해 확정한다.

3. 리뷰어 및 승인자는 작업 중인 한글화 작업 브랜치(예: dev-1.17-ko.3)에 영향을 최소화 하기 위해서, 신규 한글화 작업 브랜치(예: dev-1.17-ko.4) 생성 시점에 맞춰 확정된 PR을 승인한다. 개선된 한글화 용어집은 신규 한글화 작업 브랜치부터 적용한다.

4. 개선된 한글화 용어집에 따라 기존의 한글 문서에 대한 업데이트가 필요하며, 컨트리뷰션을 통해서 업데이트를 진행한다.

한글화 용어집