flowchart TB
subgraph third[PR 열기]
direction TB
U[ ] -.-
Q[컨텐츠 향상시키기] --- N[컨텐츠 생성하기]
N --- O[문서 번역하기]
O --- P[K8s 릴리스 사이클의 문서 파트 관리/퍼블리싱하기]
end
subgraph second[리뷰]
direction TB
T[ ] -.-
D[K8s/website 저장소 살펴보기] --- E[Hugo 정적 사이트 생성기 확인하기]
E --- F[기본 GitHub 명령어 이해하기]
F --- G[열려 있는 PR을 리뷰하기]
end
subgraph first[가입]
direction TB
S[ ] -.-
B[CNCF Contributor License Agreement 서명하기] --- C[sig-docs 슬랙 채널 가입하기]
C --- V[kubernetes-sig-docs 메일링 리스트 가입하기]
V --- M[주간 sig-docs 회의/ 슬랙 미팅 참여하기]
end
A([fa:fa-user 신규 기여자]) --> first
A --> second
A --> third
A --> H[질문하세요!!!]
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,C,D,E,F,G,H,M,Q,N,O,P,V grey
class S,T,U spacewhite
class first,second,third white
그림 1. 신규 기여자를 위한 시작 가이드.
그림 1은 신규 기여자를 위한 로드맵을 간략하게 보여줍니다. 가입 및 리뷰 단계의 일부 또는 전체를 따를 수 있습니다. 이제 PR 열기 아래에 나열된 항목들을 수행하여 당신의 기여 목표를 달성할 수 있습니다. 다시 말하지만 질문은 언제나 환영입니다!
일부 작업에는 쿠버네티스 조직에서 더 많은 신뢰와 더 많은 접근이 필요할 수 있습니다.
역할과 권한에 대한 자세한 내용은
SIG Docs 참여를 봅니다.
첫 번째 기여
몇 가지 단계를 미리 검토하여 첫 번째 기여를 준비할 수 있습니다. 그림 2는 각 단계를 설명하며, 그 다음에 세부 사항도 설명되어 있습니다.
flowchart LR
subgraph second[첫 기여]
direction TB
S[ ] -.-
G[다른 K8s 멤버의 PR 리뷰하기] -->
A[K8s/website 이슈 리스트에서 good first issue 확인하기] --> B[PR을 여세요!!]
end
subgraph first[추천 준비 사항]
direction TB
T[ ] -.-
D[기여 개요 읽기] -->E[K8s 컨텐츠 및 스타일 가이드 읽기]
E --> F[Hugo 페이지 컨텐츠 종류와 shortcode 숙지하기]
end
first ----> second
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,D,E,F,G grey
class S,T spacewhite
class first,second white
쿠버네티스 문서의 문제를 발견하거나 새로운 내용에 대한 아이디어가 있으면, 이슈를 연다. GitHub 계정과 웹 브라우저만 있으면 된다.
대부분의 경우, 쿠버네티스 문서에 대한 새로운 작업은 GitHub의 이슈로 시작된다. 그런 다음
쿠버네티스 기여자는 필요에 따라 이슈를 리뷰, 분류하고 태그를 지정한다. 다음으로, 여러분이나
다른 쿠버네티스 커뮤니티 멤버가 문제를 해결하기 위한 변경 사항이 있는 풀 리퀘스트를 연다.
이슈 열기
기존 콘텐츠에 대한 개선을 제안하고 싶거나 오류를 발견하면, 이슈를 연다.
오른쪽 사이드바에서 문서에 이슈 생성 링크를 클릭한다. 그러면 헤더가
미리 채워진 GitHub 이슈 페이지로 리디렉션된다.
개선을 위한 문제나 제안 사항을 설명한다. 가능한 한 많은 정보를 제공한다.
Submit new issue 를 클릭한다.
이슈를 제출한 후, 가끔 확인하거나 GitHub 알림을 켜자.
리뷰어와 다른 커뮤니티 멤버가 이슈에 대한 조치를 취하기 전에
여러분에게 질문을 할 수 있다.
새로운 콘텐츠 제안
새로운 콘텐츠에 대한 아이디어가 있지만, 어디로 가야 할지 확실하지 않은 경우에도
이슈를 제기할 수 있다. 다음 중 하나를 선택하면 된다.
명확하게 이슈에 대한 설명을 제공한다. 구체적으로 무엇이 누락되었거나, 오래되었거나,
잘못되었거나, 개선이 필요한 사항인지를 설명한다.
이 이슈가 사용자에게 미치는 영향을 설명한다.
주어진 이슈의 범위를 합리적인 작업 단위로 제한한다. 넓은 범위에 대한
이슈의 경우 더 작은 이슈로 분류한다. 예를 들어, "보안 문서 수정"은
너무 광범위하지만, "'네트워크 접근 제한' 주제에 세부 사항 추가"는
실행할 수 있을 정도로 구체적이다.
기존 이슈를 검색하여 새로운 이슈와 관련이 있거나 비슷한 것이 있는지
확인한다.
새로운 이슈가 다른 이슈나 풀 리퀘스트와 관련이 있는 경우, 전체 URL이나
# 문자로 시작하는 이슈나 풀 리퀘스트의 번호로
참고한다. 예를 들면, #987654 와 관련있습니다. 와 같이 하면 된다.
행동 강령을 따른다. 동료 기여자를
존중한다. 예를 들어, "문서가 끔찍하다"는 도움이
되지 않거나 예의 바르지 않은 피드백이다.
2 - 새로운 콘텐츠 기여하기
이 섹션에는 새로운 콘텐츠를 기여하기 전에 알아야 할 정보가
있다.
flowchart LR
subgraph second[시작하기 전에]
direction TB
S[ ] -.-
A[CNCF CLA 서명하기] --> B[Git 브랜치 선택하기]
B --> C[한 PR에는 한 언어에 대한 변경사항만]
C --> F[기여자 도구 확인하기]
end
subgraph first[기여 기초]
direction TB
T[ ] -.-
D[문서를 마크다운으로 작성하고 Hugo로 사이트 빌드] --- E[GitHub에 있는 소스]
E --- G['/content/../docs' 폴더에 각 언어 컨텐츠가 있음]
G --- H[Hugo 페이지 컨텐츠 종류와 shortcode 숙지하기]
end
first ----> second
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,C,D,E,F,G,H grey
class S,T spacewhite
class first,second white
그림 - 새로운 콘텐츠 기여를 위한 준비
위 그림은 새로운 콘텐츠를 제출하기 전에 알아야 할 정보를 설명한다.
해당 정보에 대한 자세한 내용은 다음과 같다.
기여에 대한 기본 사항
마크다운(Markdown)으로 쿠버네티스 문서를 작성하고
Hugo를 사용하여 쿠버네티스 사이트를 구축한다.
풀 리퀘스트를 이미 제출했는데 기본 브랜치가 잘못되었다는 것을 알게 되면,
제출자(제출자인 여러분만)가 이를 변경할 수 있다.
PR 당 언어
PR 당 하나의 언어로 풀 리퀘스트를 제한한다.
여러 언어로 동일한 코드 샘플을 동일하게 변경해야 하는 경우
각 언어마다 별도의 PR을 연다.
기여자를 위한 도구들
kubernetes/website 리포지터리의
문서 기여자를 위한 도구
디렉터리에는 기여 여정을 좀 더 순조롭게 도와주는 도구들이 포함되어 있다.
2.1 - 풀 리퀘스트 열기
참고:
코드 개발자: 향후 쿠버네티스 릴리스의
새로운 기능을 문서화하는 경우,
새 기능 문서화를 참고한다.
새 콘텐츠 페이지를 기여하거나 기존 콘텐츠 페이지를 개선하려면, 풀 리퀘스트(PR)를 연다.
시작하기 전에 섹션의
모든 요구 사항을 준수해야 한다.
변경 사항이 적거나, git에 익숙하지 않은 경우,
GitHub을 사용하여 변경하기를 읽고 페이지를 편집하는 방법을 알아보자.
변경 사항이 많으면, 로컬 포크에서 작업하기를 읽고
컴퓨터에서 로컬로 변경하는 방법을 배운다.
GitHub을 사용하여 변경하기
git 워크플로에 익숙하지 않은 경우, 풀 리퀘스트를
여는 쉬운 방법이 있다. 아래의 그림은 각 단계를 보여주며, 상세사항은 그 아래에 나온다.
flowchart LR
A([fa:fa-user 신규 기여자]) --- id1[(K8s/Website GitHub)]
subgraph tasks[GitHub 상에서 변경하기]
direction TB
0[ ] -.-
1[1. '페이지 편집' 누르기] --> 2[2. GitHub 마크다운 편집기로 편집하기]
2 --> 3[3. 'Propose file change'에 추가 내용 기재하기]
end
subgraph tasks2[ ]
direction TB
4[4. 'Propose changes' 누르기] --> 5[5. 'Create pull request' 누르기] --> 6[6. 'Open a pull request'에 추가 내용 기재하기]
6 --> 7[7. 'Create pull request' 누르기]
end
id1 --> tasks --> tasks2
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 k8s fill:#326ce5,stroke:#fff,stroke-width:1px,color:#fff;
classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000
class A,1,2,3,4,5,6,7 grey
class 0 spacewhite
class tasks,tasks2 white
class id1 k8s
그림 - GitHub 상에서 PR을 여는 단계
이슈가 있는 페이지에서, 오른쪽 상단에 있는 연필 아이콘을 선택한다.
페이지 하단으로 스크롤 하여 페이지 편집하기 를 선택할 수도 있다.
GitHub 마크다운 편집기에서 수정한다.
편집기 아래에서, Propose file change 양식을
작성한다. 첫 번째 필드에서, 커밋 메시지 제목을 지정한다.
두 번째 필드에는, 설명을 제공한다.
참고:
커밋 메시지에 [GitHub 키워드](https://help.github.com/en/github/managing-your-work-on-github/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword)를 사용하지 않는다. 나중에 풀 리퀘스트 설명에
추가할 수 있다.
Propose file change 를 선택한다.
Create pull requests 를 선택한다.
Open a pull request 화면이 나타난다. 양식을 작성한다.
풀 리퀘스트의 Subject 필드는 기본적으로 커밋의 요약으로 설정한다.
필요한 경우 변경할 수 있다.
Body 는 만약 내용이 있다면, 확장된 커밋 메시지를 포함한다.
그리고 일부 템플릿 텍스트를 포함한다.
템플릿 텍스트에 필요한 세부 정보를 추가한 다음, 추가 템플릿 텍스트를 삭제한다.
Allow edits from maintainers 체크박스는 선택된 상태로 둔다.
참고:
PR 설명은 리뷰어가 변경 사항을 이해하는 데 유용한 방법이다.
자세한 내용은 [PR 열기](#open-a-pr)를 참고한다.
Create pull request 를 선택한다.
GitHub에서 피드백 해결
풀 리퀘스트를 병합하기 전에, 쿠버네티스 커뮤니티 회원은 이를 리뷰하고
승인한다. k8s-ci-robot 은 이 페이지에 나와있는 가까운
멤버에게 리뷰를 제안한다. 특정한 사람을 염두에 두고 있다면,
GitHub 사용자 이름을 코멘트로 남긴다.
리뷰어가 변경을 요청하는 경우, 다음과 같이 한다.
Files changed 탭으로 이동 한다.
풀 리퀘스트에 의해 변경된 파일에서 연필(편집) 아이콘을
선택한다.
요청된 변경에 대한 수정을 한다.
변경 사항을 커밋한다.
리뷰어를 기다리고 있는 경우, 7일마다 한 번씩 연락한다. 슬랙 채널 #sig-docs 에 메시지를 게시할 수도 있다.
리뷰가 완료되면, 리뷰어가 PR을 병합하고 몇 분 후에 변경 사항이 적용된다.
로컬 포크에서 작업하기
git에 익숙하거나, 변경 사항이 몇 줄보다 클 경우,
로컬 포크로 작업한다.
컴퓨터에 git이 설치되어 있는지 확인한다.
git UI 애플리케이션을 사용할 수도 있다.
아래 그림은 로컬 포크에서 작업할 때의 단계를 나타낸다. 상세 사항도 소개되어 있다.
flowchart LR
1[K8s/website 저장소 포크하기] --> 2[로컬 클론 생성 및 upstream 설정]
subgraph changes[당신의 변경사항]
direction TB
S[ ] -.-
3[브랜치 생성 예: my_new_branch] --> 3a[텍스트 편집기로 변경사항 만들기] --> 4["Hugo (localhost:1313) 를 이용하거나 컨테이너 이미지를 빌드하여 변경사항을 로컬에서 미리보기"]
end
subgraph changes2[커밋 / 푸시]
direction TB
T[ ] -.-
5[변경사항 커밋하기] --> 6[커밋을 origin/my_new_branch 로 푸시하기]
end
2 --> changes --> changes2
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 k8s fill:#326ce5,stroke:#fff,stroke-width:1px,color:#fff;
classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000
class 1,2,3,3a,4,5,6 grey
class S,T spacewhite
class changes,changes2 white
포크의 origin/main 와 kubernetes/website 의 upstream/main 에서 커밋을 가져온다.
git fetch origin
git fetch upstream
이를 통해 변경을 시작하기 전에 로컬 리포지터리가 최신 상태인지 확인한다.
참고:
이 워크플로는
[쿠버네티스 커뮤니티 GitHub 워크플로](https://github.com/kubernetes/community/blob/master/contributors/guide/github-workflow.md)
와 다르다.
포크에 업데이트를 푸시하기 전에 로컬의 `main` 복사본을 `upstream/main` 와 병합할 필요가 없다.
브랜치 만들기
작업할 브랜치 기반을 결정한다.
기존 콘텐츠를 개선하려면, upstream/main 를 사용한다.
기존 기능에 대한 새로운 콘텐츠를 작성하려면, upstream/main 를 사용한다.
현지화된 콘텐츠의 경우, 현지화 규칙을 사용한다. 자세한 내용은 쿠버네티스 문서 현지화를 참고한다.
다가오는 쿠버네티스 릴리스의 새로운 기능에 대해서는 기능 브랜치(feature branch)를 사용한다.
자세한 정보는 릴리스 문서화를 참고한다.
콘텐츠 재구성과 같이 여러 SIG Docs 기여자들이 협업하는 장기적인 작업에는,
해당 작업을 위해 작성된 특정 기능 브랜치를
사용한다.
브랜치 선택에 도움이 필요하면, 슬랙 채널 #sig-docs 에 문의한다.
1단계에서 식별된 브랜치를 기반으로 새 브랜치를 작성한다.
이 예에서는 기본 브랜치가 upstream/main 라고 가정한다.
git checkout -b <my_new_branch> upstream/main
텍스트 편집기를 사용하여 변경한다.
언제든지, git status 명령을 사용하여 변경한 파일을 본다.
변경 사항 커밋
풀 리퀘스트를 제출할 준비가 되면, 변경 사항을 커밋한다.
로컬 리포지터리에서 커밋해야 할 파일을 확인한다.
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")
Changes not staged for commit 에 나열된 파일을 커밋에 추가한다.
git add <your_file_name>
각 파일에 대해 이 작업을 반복한다.
모든 파일을 추가한 후, 커밋을 생성한다.
git commit -m "Your commit message"
참고:
커밋 메시지에 [GitHub 키워드](https://help.github.com/en/github/managing-your-work-on-github/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword)를 사용하지 말자.
나중에 풀 리퀘스트 설명에 추가할
수 있다.
로컬 브랜치와 새로운 커밋을 원격 포크로 푸시한다.
git push origin <my_new_branch>
로컬에서 변경 사항 미리보기
변경 사항을 푸시하거나 풀 리퀘스트를 열기 전에 변경 사항을 로컬에서 미리 보는 것이 좋다.
미리보기를 사용하면 빌드 오류나 마크다운 형식 문제를 알아낼 수 있다.
website의 컨테이너 이미지를 만들거나 Hugo를 로컬에서 실행할 수 있다.
도커 이미지 빌드는 느리지만 Hugo 단축코드를 표시하므로,
디버깅에 유용할 수 있다.
PR에 여러 커밋이 있는 경우, PR을 병합하기 전에 해당 커밋을 단일 커밋으로 스쿼시해야 한다.
PR의 Commits 탭에서 또는 git log 명령을 로컬에서 실행하여
커밋 수를 확인할 수 있다.
참고:
여기서는 vim 을 커맨드 라인 텍스트 편집기로 사용하는 것을 가정한다.
대화식 리베이스를 시작한다.
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 에 집중한다.
참고:
자세한 내용은 [대화식 모드](https://git-scm.com/docs/git-rebase#_interactive_mode)를 참고한다.
숙련된 기여자인 경우, 작업에 광범위한 변경이 필요한 새 기여자와 쌍을 이루어 리뷰해 본다.
리뷰 과정
일반적으로, 영어로 콘텐츠와 스타일에 대한 풀 리퀘스트를 리뷰한다. 그림 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
cncf-cla: yes(권장): CLA에 서명하지 않은 기여자가 제출한 PR은 병합할 수 없다.
자세한 내용은 CLA 서명을
참고한다.
language/en(권장): 영어 문서에 대한 PR 전용 필터이다.
size/<size>: 특정 크기의 PR을 필터링한다. 새로 시작하는 사람이라면, 더 작은 PR로 시작한다.
또한, PR이 진행 중인 작업으로 표시되지 않았는지 확인한다.
work in progress 레이블을 사용하는 PR은 아직 리뷰할 준비가 되지 않은 PR이다.
리뷰할 PR을 선택한 후, 다음을 통해 변경 사항을 이해한다.
PR 설명을 통해 변경 사항을 이해하고, 연결된 이슈 읽기
다른 리뷰어의 의견 읽기
Files changed 탭을 클릭하여 변경된 파일과 행 보기
Conversation 탭의 맨 아래에 있는 PR의 빌드 확인 섹션으로 스크롤하여
Netlify 미리보기 빌드의 변경 사항을 확인.
다음은 스크린샷이다(GitHub 데스크탑 사이트이며,
태블릿 또는 스마트폰 장치에서 리뷰하는 경우 GitHub 웹 UI가 약간 다르다).
미리보기를 열려면,
체크 목록의 deploy/netlify 행의 Details 링크를 클릭한다.
Files changed 탭으로 이동하여 리뷰를 시작한다.
코멘트을 달려는 줄 옆에 있는 + 기호를 클릭한다.
행에 대한 의견을 작성하고 Add single comments(작성할 의견이 하나만 있는 경우)
또는 Start a review(작성할 의견이 여러 개인 경우)를 클릭한다.
완료되면, 페이지 상단에서 Review changes 를 클릭한다. 여기에서
리뷰에 대한 요약을 추가한다(기여자에게 긍정적인 의견을 남겨주기 바란다!).
항상 Comment 를 선택해야 한다.
리뷰를 완료할 때, "Request changes" 버튼을 누르지 않는다.
만약 몇몇 변경사항들이 반영되기 전에 PR이 병합되는 것을 막고 싶다면,
"/hold" 명령어를 사용한다.
왜 "/hold"를 사용하는지 언급해줘야 하며, 어떤 경우에 홀드가 제거되는지에
대해서 명세해주는 것은 기여자에게 도움이 된다.
리뷰를 완료할 때, "Approve" 버튼을 누르지 않는다.
대부분의 경우 "/approve" 명령어를 대신 사용한다.
리뷰 체크리스트
리뷰할 때, 다음을 시작점으로 사용한다.
언어와 문법
언어나 문법에 명백한 오류가 있는가? 무언가를 표현하는 더 좋은 방법이 있는가?
기여자가 변경한 부분의 언어와 문법에 집중한다.
기여자가 문서 전체를 갱신하는 것을 목표로 하지 않는 한,
해당 문서의 모든 이슈들을 해결할 의무는 없다.
PR이 기존의 문서를 갱신하는 경우, 갱신된 부분을 검토하는데 집중한다.
변경된 내용이 기술적으로, 그리고 문서적으로 정확한지
검토한다.
기여자가 해결하려는 문제와 직접적으로 관련 있지는 않은 문제들을 발견할 경우,
개별적인 이슈로써 처리한다
(그 전에 해당 문제가 이슈화 되어있는지 확인한다).
문서의 경로를 _이동_한 PR이 있는지 주의한다.
기여자가 문서의 이름을 변경하거나 두개 이상의 문서들을 합치는 경우, 우리(쿠버네티스 SIG Docs)는
이동된 문서에서 발견할 수 있는 모든 문법이나 철자를 수정하도록 요청하지는 않는다.
변경 사항이 Netlify 미리보기에 표시되는가?
목록, 코드 블록, 표, 메모 및 이미지에 특히 주의한다.
기타
사소한 내용만을 가지고 기여하는 것에 주의한다;
사소한 수정으로 간주할 수 있는 수정 요청을 발견한다면, 해당 정책을 알려주는 것이 바람직하다
(실질적인 개선 사항이라면 수용 가능함).
공백을 수정하는 기여자들로 하여금,
PR의 첫번째 커밋에서 공백을 수정한 뒤 다른 변경 사항들을 추가하도록 권장한다.
이는 검토와 병합 과정을 더욱 쉽게 한다.
특히 대량으로 공백을 정리하는 하나의 커밋에서 발생하는 사소한 변경사항들에 주의한다.
(만약 이를 확인한 경우, 기여자에게 수정을 권장하도록 한다.)
리뷰어로써, PR에서 공백 문제나 오타 등 크게 중요하지 않은 사소한 이슈들을 발견하는 경우,
리뷰 앞에 nit:을 붙인다.
이렇게 함으로써 기여자가 해당 피드백이 크게 중요하지 않다는 것을 알 수 있다.
nit으로 표시된 피드백을 제외하고 모든 이슈들을 해결한 PR은 병합할 수 있다.
이러한 경우, 아직 해결되지 않는 nit 사항들에 대하여 새롭게 이슈를 여는 것을 권장한다.
또한 새로운 이슈를 Good First Issue]로써
표시할 수 있는지에 대해 고려해본다.
가능한 경우, 이것은 새로운 기여자에게 좋은 소스가 된다.
매주 특정 문서 승인자 역할의 지원자가
풀 리퀘스트를 심사하고 리뷰한다. 이
사람은 일주일 동안 "PR 랭글러(Wrangler)"이다. 자세한
정보는 PR 랭글러 스케줄러를 참고한다. PR 랭글러가 되려면, 매주 SIG Docs 회의에 참석하고 자원한다. 이번 주에 해당 일정이 없는 경우에도, 아직 리뷰 중이 아닌
풀 리퀘스트(PR)를 여전히 리뷰할 수 있다.
로테이션 외에도, 봇은 영향을 받는 파일의 소유자를 기반으로
PR에 대한 리뷰어와 승인자를 할당한다.
Prow는
풀 리퀘스트 (PR)에 대한 작업을 실행하는 쿠버네티스 기반 CI/CD 시스템이다. Prow는
챗봇 스타일 명령으로 쿠버네티스
조직 전체에서 레이블 추가와 제거, 이슈 종료 및 승인자 할당과 같은 GitHub 작업을 처리할 수 있다. /<command-name> 형식을 사용하여 Prow 명령을 GitHub 코멘트로 입력한다.
이슈는 일반적으로 신속하게 열리고 닫힌다.
그러나, 가끔씩은 이슈가 열린 후 비활성 상태로 있다.
어떤 경우에는 이슈가 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년이 지난 블로그 항목과 관련된 이슈일 경우,
수정하지 않고 이슈를 닫는다.
지원 요청 또는 코드 버그 리포트
문서에 대한 일부 이슈는 실제로 기본 코드와 관련된 이슈이거나, 튜토리얼과
같은 무언가가 작동하지 않을 때 도움을 요청하는 것이다.
문서와 관련이 없는 이슈의 경우, 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 에서
이슈를 여십시오.
문서에 대한 이슈인 경우 이 이슈를 다시 여십시오.
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 플러그인을
사용한다.
blunderbuss
approve
이 두 플러그인은 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 의장과
같은 특정 역할도 수행한다.
퀵윈(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 랭글링 과정을 이해하는 데 도움을 주기 위해 도입되었다.
섀도우 되기
PR 랭글러 섀도우 활동에 관심이 있다면, PR 랭글러 위키 페이지에서 올해의 PR 랭글링 스케줄을 확인하고 지원한다.
쿠버네티스 org 멤버는 PR 랭글러 위키 페이지를 수정하여 기존 PR 랭글러를 1주일 간 섀도잉할 수 있다.
위에 나열된 도구들 (예: Go 바이너리나 python) 을 사용할 수 있도록 PATH 환경 변수를 알맞게 설정해야 한다.
GitHub 저장소로 풀 리퀘스트를 생성하는 방법을 알고 있어야 한다.
이를 위해 kubernetes/website 저장소를 개인 계정으로 포크해야 한다.
더 자세한 내용은 로컬 포크에서 작업하기를 참조한다.
website 저장소 클론하기
개인 계정에 있는 포크 버전의 website 저장소가 GitHub에 있는 kubernetes/website 저장소(main 브랜치)의 최신 상태와 일치하는지 확인한 뒤,
개인 계정에 있는 포크 버전의 website 저장소를 로컬 개발 환경으로 클론한다.
mkdir github.com
cd github.com
git clone git@github.com:<your_github_username>/website.git
아래에서 사용될 '베이스 디렉터리'를 숙지해야 한다. 예를 들어 위에 안내된 대로
저장소를 클론했다면, 베이스 디렉터리는
github.com/website 가 된다. 이제 이 문서의 나머지 부분에서 <web-base> 라는 구문이 나오면
이 부분에 당신의 베이스 디렉터리를 대입하면 된다.
update-imported-docs.py 스크립트는 <web-base>/update-imported-docs/
디렉터리에 존재한다.
이 스크립트는 다음 레퍼런스를 생성한다.
구성요소 및 도구 레퍼런스 페이지
kubectl 명령어 레퍼런스
쿠버네티스 API 레퍼런스
update-imported-docs.py 스크립트는 쿠버네티스 소스코드로부터 레퍼런스 문서를
생성한다. 스크립트가 실행되면 개발 머신의 /tmp 디렉터리 아래에 임시 디렉터리를
생성하고, 이 임시 디렉터리 아래에 레퍼런스 문서 생성에 필요한 kubernetes/kubernetes 저장소와
kubernetes-sigs/reference-docs 저장소를 클론하며,
GOPATH 환경 변수를 이 임시 디렉터리로 지정한다.
또한 이 스크립트는 다음의 환경 변수를 설정한다.
K8S_RELEASE
K8S_ROOT
K8S_WEBROOT
스크립트가 정상적으로 실행되려면 인자 2개를 전달해야 한다.
환경설정 YAML 파일 (reference.yml)
쿠버네티스 릴리스 버전 (예: 1.17)
환경설정 파일은 generate-command 라는 필드를 포함하는데,
이 필드에는
kubernetes-sigs/reference-docs/Makefile 에 있는 Make 타겟들을 활용하여 빌드하는 일련의 과정이 명시되어 있다.
K8S_RELEASE 환경 변수는 릴리스 버전을 결정한다.
update-imported-docs.py 스크립트는 다음의 과정을 수행한다.
환경설정 파일에 있는 관련 저장소를 클론한다.
레퍼런스 문서 생성을 위해
기본적으로는 kubernetes-sigs/reference-docs 저장소를 클론하도록 되어 있다.
클론한 안에서, 문서 생성에 필요한 사항을 준비하기 위한 명령어를 실행한 뒤,
HTML 파일과 마크다운 파일을 생성한다.
생성된 HTML 파일과 마크다운 파일을
환경설정 파일에 명시된 규칙에 따라 <web-base> 로 복사한다.
kubectl.md 에 있는 kubectl 명령어 링크들이
kubectl 명령어 레퍼런스 페이지의 올바른 섹션으로 연결되도록 업데이트한다.
생성된 파일이 <web-base> 아래에 복사되었으면,
kubernetes/website 저장소로 풀 리퀘스트를 생성
할 수 있다.
환경설정 파일 형식
각 환경설정 파일은 레퍼런스 생성을 위해 필요한 여러 저장소의 정보를 담을 수 있다.
필요한 경우, 환경설정 파일을 직접 수정하여 사용할 수도 있다.
또는, 다른 그룹의 문서를 임포트하기 위해 새로운 환경설정 파일을 작성할 수도 있다.
다음은 환경설정 YAML 파일의 예시이다.
이 도구에 의해 처리될 단일 페이지 마크다운 문서는
문서 스타일 가이드의 내용을 만족해야 한다.
reference.yml 환경설정 파일 다루기
<web-base>/update-imported-docs/reference.yml 환경설정 파일을 열어 수정할 수 있다.
레퍼런스 문서 생성을 위해 명령어들이 어떻게 사용되고 있는지 파악하지 못했다면,
generate-command 필드의 내용은 수정하지 말아야 한다.
대부분의 경우 reference.yml 을 직접 수정해야 할 필요는 없다.
때때로, 업스트림 소스코드 업데이트 때문에 이 환경설정 파일을 수정해야 할 수도 있다.
(예: Golang 버전 의존성, 써드파티 라이브러리 변경 등)
만약 스크립트 사용 시 빌드 문제가 있다면,
쿠버네티스 슬랙의 #sig-docs 채널에서 SIG-Docs 팀에 문의하면 된다.
참고:
generate-command 는 특정 저장소로부터 문서를 만들기 위한
명령어나 스크립트를 실행하기 위해 사용할 수 있는 선택적 필드이다.
reference.yml 환경설정 파일에서, files 필드는 src 와 dst 필드를 포함한다.
src 필드에는 kubernetes-sigs/reference-docs 디렉터리 아래에 있는 생성된 마크다운 파일의 위치를 명시하고,
dst 필드에는 이 파일을
kubernetes/website 디렉터리 아래의 어느 위치로 복사할지를 명시한다.
예시는 다음과 같다.
개념 페이지는 쿠버네티스의 일부 측면을 설명한다. 예를 들어 개념 페이지는 쿠버네티스 디플로이먼트 오브젝트를 설명하고 배치, 확장 및 업데이트되는 동안 애플리케이션으로서 수행하는 역할을 설명할 수 있다. 일반적으로 개념 페이지는 일련의 단계가 포함되지 않지만 대신 태스크나 튜토리얼에 대한 링크를 제공한다. 개념 문서의 예로서 노드를 참조하자.
태스크
태스크 페이지는 단일 작업을 수행하는 방법을 보여준다. 아이디어는 독자가 페이지를 읽을 때 실제로 수행할 수 있는 일련의 단계를 제공하는 것이다. 태스크 페이지는 한 영역에 집중되어 있으면 짧거나 길 수 있다. 태스크 페이지에서 수행할 단계와 간단한 설명을 혼합하는 것은 괜찮지만, 긴 설명을 제공해야 하는 경우에는 개념 문서에서 수행해야 한다. 관련 태스크와 개념 문서는 서로 연결되어야 한다. 짧은 태스크 페이지의 예제는 저장소에 볼륨을 사용하도록 파드 구성을 참조하자. 더 긴 태스크 페이지의 예제는 활동성 및 준비성 프로브 구성을 참조하자.
튜토리얼
튜토리얼 페이지는 여러 쿠버네티스의 특징들을 하나로 묶어서 목적을 달성하는 방법을 보여준다. 튜토리얼은 독자들이 페이지를 읽을 때 실제로 할 수 있는 몇 가지 단계의 순서를 제공한다. 또는 관련 코드 일부에 대한 설명을 제공할 수도 있다. 예를 들어 튜토리얼은 코드 샘플의 연습을 제공할 수 있다. 튜토리얼에는 쿠버네티스의 특징에 대한 간략한 설명이 포함될 수 있지만 개별 기능에 대한 자세한 설명은 관련 개념 문서과 연결지어야 한다.
새 페이지 작성
작성하는 각각의 새 페이지에 대해 콘텐츠 타입을
사용하자. 문서 사이트는 새 콘텐츠 페이지를 작성하기 위한 템플리트 또는
Hugo archetypes을
제공한다. 새로운 타입의 페이지를 작성하려면, 작성하려는 파일의 경로로 hugo new 를
실행한다. 예를 들면, 다음과 같다.
hugo new docs/concepts/my-first-concept.md
제목과 파일 이름 선택
검색 엔진에서 찾을 키워드가 있는 제목을 선택하자.
제목에 있는 단어를 하이픈으로 구분하여 사용하는 파일 이름을 만들자.
예를 들어
HTTP 프록시를 사용하여 쿠버네티스 API에 접근
이라는 제목의 문서는 http-proxy-access-api.md라는 이름의 파일을 가진다.
"쿠버네티스"가 이미 해당 주제의 URL에 있기 때문에 파일 이름에 "쿠버네티스" 를 넣을 필요가 없다.
예를 들면 다음과 같다.
문서에서 전문
에 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 파일을
포함할 수 있다.
더 큰 파일의 일부분을 강조하기 위한 불완전한 예제 코드.
예를 들어 롤바인딩(RoleBinding)
에 대한 사용자 정의 방법을 설명할 때,
문서 파일에서 직접 짧은 요약 정보를 제공할 수 있다.
사용자가 다른 이유로 시도하기 위한 것이 아닌 코드. 예를 들어
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 파일을 참조한다.
<LANG>/examples 디렉터리에 새 YAMl 파일을 추가할 때 파일이
<LANG>/examples_test.go 파일에도 포함되어 있는지 확인하자.
웹 사이트의 Travis CI 는 PR이 제출될 때 이 예제를 자동으로
실행하여 모든 예제가 테스트를 통과하도록 한다.
한 동안 쿠버네티스 문서에 기여한 후에,
스타일 가이드,
컨텐츠 가이드, 문서 작성에 사용되는 툴체인,
website 스타일, 풀 리퀘스트 리뷰와 병합
프로세스 또는 문서 작성의 다른 측면을 개선하기 위한 아이디어가 있을 수 있다. 투명성을 극대화하려면,
이러한 유형의 제안을 SIG Docs 회의나
kubernetes-sig-docs 메일링리스트에서 논의해야 한다.
또한, 획기적인 변경을 제안하기 전에, 현재의 작업 방식과 과거의 결정이
어떻게 정해졌는지에 대한 맥락을 이해하는 데 실제로
도움이 될 수 있다. 현재의 문서 작업이 어떻게 진행되는지에 대한 질문의
답변을 얻는 가장 빠른 방법은 kubernetes.slack.com의
#sig-docs 슬랙 채널에 문의하는 것이다.
토론이 진행되고 원하는 결과에 SIG가 동의한
후에는, 제안한 변경 사항과 가장 적합한 방식으로
작업할 수 있다. 예를 들어, 스타일 가이드나 website의
기능을 업데이트하려면, sig-testing과 함께 작업이 필요할 수 있는
문서 테스트와 관련된 변경에 대해 풀 리퀘스트를 열어야 할 수 있다.
각 쿠버네티스 릴리스는 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 승인자
사이에서 의무가 순환된다.
새로운 기여자가 하나 이상의 쿠버네티스 리포지터리에 5개의
실질적인 풀 리퀘스트를 성공적으로 제출한 후에는
쿠버네티스 조직의 멤버십을
신청할 수 있다. 기여자의 멤버십은 이미 리뷰어인 두 명의 스폰서가
후원해야 한다.
새로운 문서 기여자는 쿠버네티스 슬랙 인스턴스의 #sig-docs
채널이나 SIG Docs 메일링리스트에서
스폰서를 요청할 수 있다.
신청자의 작업에 대해 확신이 있다면, 리뷰어는 신청자를 후원한다.
신청자가 멤버십 신청서를 제출할 때, 신청서에 "+1"로 코멘트를 남기고
신청자가 쿠버네티스 조직의 멤버십에
적합한 이유에 대한 세부 정보를 포함한다.
SIG Docs 커뮤니티에 이해 직접적으로 또는 lazy consensus(특정 기간 내에 아무런 의견이 없으면 통과)를 통해 승인된다.
최소 6개월 동안 일주일에 5시간 이상(대부분 더)을 역할에 책임진다.
책임
공동 의장의 역할은 서비스 중 하나이다. 공동 의장은 기여자 역량 확보, 프로세스와 정책 처리, 회의 예약과 진행, PR 랭글러 스케줄링, 쿠버네티스 커뮤니티의 문서에 대한 지지, 쿠버네티스 릴리스 주기에서 성공적으로 문서화되는지 확인하고, SIG Docs를 효과적인 우선순위에 놓이도록 집중한다.
다음과 같은 책임을 가진다.
SIG Docs가 우수한 문서화를 통해 개발자의 행복을 극대화하는 데 집중한다.
스스로가 커뮤니티 행동 강령을 준수하여 예를 보이고, SIG 멤버들이 지킬 수 있도록 책임을 진다.
기여에 대한 새로운 지침을 확인하여 SIG에 대한 모범 사례를 배우고 설정한다.
SIG 회의를 예약하고 진행한다. 주간 상태 업데이트, 브랜치별 회고/기획 세션과 필요에 따라 그 외 세션을 진행한다.
KubeCon 이벤트 및 기타 컨퍼런스에서 문서 스프린트를 스케줄링하고 진행한다.
CNCF와 플래티넘 파트너인 Google, Oracle, Azure, IBM 및 Huawei를 통해 SIG Docs를 대신하여 채용과 지지를 보낸다.
SIG를 원활하게 운영한다.
효과적인 회의 운영
효과적으로 회의를 예약하고 진행하기 위해, 이 지침은 수행할 작업, 수행 방법과 이유를 보여준다.
이 대시보드는 Google Data Studio를 사용하여 구축되었으며 kubernetes.io에서 Google Analytics를 사용하여 수집한 정보를 보여준다.
대시보드 사용
기본적으로 대시보드는 지난 30일 동안 수집된 모든 데이터의 분석을 제공한다. 날짜 선택을 통해 특정 날짜 범위의 데이터를 볼 수 있다. 그 외 필터링 옵션을 사용하면, 사용자의 위치, 사이트에 접속하는데 사용된 장치, 번역된 문서 언어 등을 기준으로 데이터를 확인할 수 있다.
쿠버네티스 문서 한글화팀은 커뮤니티의
현지화 가이드에 따라 한글화를
위한 팀 마일스톤과 개발 브랜치를 관리한다. 본 섹션은 한글화팀의 팀 마일스톤 관리에 특화된
내용을 다룬다.
한글화팀은 main 브랜치에서 분기한 개발 브랜치를 사용한다. 개발 브랜치 이름은 다음과 같은
구조를 갖는다.
dev-<소스 버전>-ko.<팀 마일스톤>
개발 브랜치는 약 2주에서 3주 사이의 팀 마일스톤 기간 동안 공동의 작업을 위해 사용되며, 팀
마일스톤이 종료될 때 원 브랜치로 병합(merge)된다.
업스트림(upstream)의 릴리스 주기(약 3개월)에 따라 다음 버전으로 마일스톤을 변경하는 시점에는
일시적으로 release-<소스 버전> 브랜치를 원 브랜치로 사용하는 개발 브랜치를 추가로 운영한다.
한글화팀의 정기 화상 회의 일정과
팀 마일스톤 주기는 대체로 일치하며, 정기 회의를 통해 팀 마일스톤마다 PR 랭글러(wrangler)를
지정한다.
한글화팀의 PR 랭글러가 갖는 의무는 업스트림의
PR 랭글러가 갖는
의무와 유사하다. 단, 업스트림의 PR 랭글러와는 달리 승인자가 아니어도 팀 마일스톤의 PR 랭글러가
될 수 있다. 그래서, 보다 상위 권한이 필요한 업무가 발생한 경우, PR 랭글러는 해당 권한을 가진
한글화팀 멤버에게 처리를 요청한다.
단, 해당 원칙에는 예외가 있을 수 있으며, 이 경우에는 가능한
한글화 용어집을 준용한다.
참고:
기능 게이트는 쿠버네티스 버전에 따라 변경될 수 있으므로,
쿠버네티스 및 쿠버네티스 문서의 버전에 맞는 기능 게이트 목록을 적용하여 한글화를 진행한다.
한글화 용어집 정보
쿠버네티스 한글화 용어집은 한글화된 쿠버네티스 문서의 일관성을 위해서
각 영문 용어에 대한 한글화 방법을 제시한다.
한글화 용어집에 포함된 용어는 쿠버네티스 문서 한글화팀 회의를 통해 결정되었으며,
본 문서에 대한 ISSUE 및 PR을 통해서 개선한다.
한글화 용어집 개선 가이드
한글화 용어집의 개선(추가, 수정, 삭제 등)을 위한 과정은 다음과 같다.
컨트리뷰터가 개선이 필요한 용어을 파악하면, ISSUE를 생성하여 개선 필요성을 공유하거나 main 브랜치에
PR을 생성하여 개선된 용어를 제안한다.
개선 제안에 대한 논의는 ISSUE 및 PR을 통해서 이루어지며, 한글화팀 회의를 통해 확정한다.
리뷰어 및 승인자는 작업 중인 한글화 작업 브랜치(예: dev-1.17-ko.3)에 영향을 최소화 하기 위해서,
신규 한글화 작업 브랜치(예: dev-1.17-ko.4) 생성 시점에 맞춰 확정된 PR을 승인한다.
개선된 한글화 용어집은 신규 한글화 작업 브랜치부터 적용한다.
개선된 한글화 용어집에 따라 기존의 한글 문서에 대한 업데이트가 필요하며,
컨트리뷰션을 통해서 업데이트를 진행한다.
한글화 용어집
English
한글
비고
Access
접근
Active
Active
잡의 상태
Active Job
액티브 잡
Addons
애드온
admission controller
어드미션 컨트롤러
Age
기간
Allocation
할당량
alphanumeric
영숫자
Annotation
어노테이션
APIService
API서비스(APIService)
API 오브젝트인 경우
App
앱
Appendix
부록
Application
애플리케이션
Args
Args
약어의 형태이므로 한글화하지 않고 영문 표기
array
배열
autoscaler
오토스케일러
availability zone
가용성 영역(availability zone)
bare pod
베어(bare) 파드
beta
베타
Binding
바인딩(Binding)
API 오브젝트인 경우
boilerplate
상용구
Boot
부트
Bootstrap
부트스트랩
Build
빌드
Cache
캐시
Calico
캘리코(Calico)
canary
카나리(canary)
릴리스 방식에 관련한 용어인 경우에 한함
cascading
캐스케이딩(cascading)
CertificateSigningRequest
CertificateSigningRequest
API 오브젝트인 경우
character set
캐릭터 셋
Charts
차트
checkpoint
체크포인트
Cilium
실리움(Cilium)
CLI
CLI
Cluster
클러스터
ClusterRole
클러스터롤(ClusterRole)
API 오브젝트인 경우
ClusterRoleBinding
클러스터롤바인딩(ClusterRoleBinding)
API 오브젝트인 경우
Command Line Tool
커맨드라인 툴
ComponentStatus
컴포넌트스테이터스(ComponentStatus)
API 오브젝트인 경우
ConfigMap
컨피그맵(ConfigMap)
API 오브젝트인 경우
configuration
구성, 설정
Connection
연결
containerized
컨테이너화 된
Context
컨텍스트
Control Plane
컨트롤 플레인
controller
컨트롤러
ControllerRevision
컨트롤러리비전(ControllerRevision)
API 오브젝트인 경우
cron job
크론 잡
CronJob
크론잡(CronJob)
API 오브젝트인 경우
CSIDriver
CSI드라이버(CSIDriver)
API 오브젝트인 경우
CSINode
CSI노드(CSINode)
API 오브젝트인 경우
custom metrics
사용자 정의 메트릭
custom resource
사용자 정의 리소스
CustomResourceDefinition
커스텀리소스데피니션(CustomResourceDefinition)
API 오브젝트인 경우
Daemon
데몬
DaemonSet
데몬셋(DaemonSet)
API 오브젝트인 경우
Dashboard
대시보드
Data Plane
데이터 플레인
Deployment
디플로이먼트(Deployment)
API 오브젝트인 경우
deprecated
사용 중단(deprecated)
descriptor
디스크립터, 식별자
Desired number of pods
의도한 파드의 수
Desired State
의도한 상태
disruption
중단(disruption)
distros
배포판
Docker
도커
Dockerfile
Dockerfile
Docker Swarm
Docker Swarm
Downward API
다운워드(Downward) API
draining
드레이닝(draining)
egress
이그레스, 송신(egress)
endpoint
엔드포인트
EndpointSlice
엔드포인트슬라이스(EndpointSlice)
API 오브젝트인 경우
Endpoints
엔드포인트(Endpoints)
API 오브젝트인 경우
entry point
진입점
Event
이벤트(Event)
API 오브젝트인 경우
evict
축출하다
eviction
축출
Exec
Exec
expose
노출시키다
extension
익스텐션(extension)
Failed
Failed
파드의 상태에 한함
Federation
페더레이션
field
필드
finalizer
파이널라이저(finalizer)
Flannel
플란넬(Flannel)
form
형식
Google Compute Engine
Google Compute Engine
hash
해시
headless
헤드리스
health check
헬스 체크
Heapster
힙스터(Heapster)
Heartbeat
하트비트
Homebrew
Homebrew
hook
훅(hook)
Horizontal Pod Autoscaler
Horizontal Pod Autoscaler
예외적으로 API 오브젝트에 대해 외래어 표기법 적용하지 않고 원문 그대로 표기
hosted zone
호스팅 영역
hostname
호스트네임
Huge page
Huge page
Hypervisor
하이퍼바이저
idempotent
멱등성
Image
이미지
Image Pull Secrets
이미지 풀(Pull) 시크릿
Ingress
인그레스(Ingress)
API 오브젝트인 경우
IngressClass
인그레스클래스(IngressClass)
API 오브젝트인 경우
Init Container
초기화 컨테이너
Instance group
인스턴스 그룹
introspection
인트로스펙션(introspection)
Istio
이스티오(Istio)
Job
잡(Job)
API 오브젝트인 경우
kube-proxy
kube-proxy
Kubelet
Kubelet
Kubernetes
쿠버네티스
Kube-router
Kube-router
label
레이블
Lease
리스(Lease)
API 오브젝트인 경우
lifecycle
라이프사이클
LimitRange
리밋레인지(LimitRange)
API 오브젝트인 경우
limit
한도(limit)
리소스의 개수나 용량을 한정하기 위한 수치로 사용된 경우 선택적으로 사용 (API 오브젝트의 속성으로 limit을 사용한 경우는 가능한 영문 유지)
