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 리포지터리의
문서 기여자를 위한 도구
디렉터리에는 기여 여정을 좀 더 순조롭게 도와주는 도구들이 포함되어 있다.
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)를 참고한다.