새로운 콘텐츠 기여하기

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

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

시작하기 전에

CNCF CLA 서명

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

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

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

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

시나리오브랜치
현재 릴리스의 기존 또는 새로운 영어 콘텐츠main
기능 변경 릴리스의 콘텐츠dev-<version> 패턴을 사용하여 기능 변경이 있는 주 버전과 부 버전에 해당하는 브랜치. 예를 들어, v1.35 에서 기능이 변경된 경우, dev-1.35 에 문서 변경을 추가한다.
다른 언어로된 콘텐츠(현지화)현지화 규칙을 사용. 자세한 내용은 현지화 브랜치 전략을 참고한다.

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

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을 여는 단계

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

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

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

  4. Propose file change 를 선택한다.

  5. Create pull requests 를 선택한다.

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

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

GitHub에서 피드백 해결

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

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

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

리뷰어를 기다리고 있는 경우, 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

그림 - 로컬 포크에서 변경 사항 작업하기

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

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

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

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

    git clone git@github.com/<github_username>/website
    cd website
    git submodule update --init --recursive --depth 1
    
  2. website 디렉터리로 이동한다. kubernetes/website 리포지터리를 upstream 원격으로 설정한다.

    cd website
    
    git remote add upstream https://github.com/kubernetes/website.git
    
  3. originupstream 리포지터리를 확인한다.

    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.git (fetch)
    upstream	https://github.com/kubernetes/website.git (push)
    
  4. 포크의 origin/mainkubernetes/websiteupstream/main 에서 커밋을 가져온다.

    git fetch origin
    git fetch upstream
    

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

브랜치 만들기

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

    • 기존 콘텐츠를 개선하려면, upstream/main 를 사용한다.
    • 기존 기능에 대한 새로운 콘텐츠를 작성하려면, upstream/main 를 사용한다.
    • 현지화된 콘텐츠의 경우, 현지화 규칙을 사용한다. 자세한 내용은 쿠버네티스 문서 현지화를 참고한다.
    • 다가오는 쿠버네티스 릴리스의 새로운 기능에 대해서는 기능 브랜치(feature branch)를 사용한다. 자세한 정보는 릴리스 문서화를 참고한다.
    • 콘텐츠 재구성과 같이 여러 SIG Docs 기여자들이 협업하는 장기적인 작업에는, 해당 작업을 위해 작성된 특정 기능 브랜치를 사용한다.

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

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

    git checkout -b <my_new_branch> upstream/main
    
  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"
    
  4. 로컬 브랜치와 새로운 커밋을 원격 포크로 푸시한다.

    git push origin <my_new_branch>
    

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

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

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

  1. 로컬에서 이미지를 빌드한다. Hugo 도구 자체에 대한 변경을 테스트하는 경우에만 이 단계가 필요하다.

    # 터미널에서 명령 실행 (필요에 따라)
    make container-serve
    
  2. 컨테이너에서 Hugo를 시작한다.

    # 터미널에서 실행
    make container-serve
    
  3. 웹 브라우저에서 http://localhost:1313 로 이동한다. Hugo는 변경 사항을 보고 필요에 따라 사이트를 다시 구축한다.

  4. 로컬의 Hugo 인스턴스를 중지하려면, 터미널로 돌아가서 Ctrl+C 를 입력하거나, 터미널 창을 닫는다.

또는, 컴퓨터에 hugo 명령을 설치하여 사용한다.

  1. website/netlify.toml에 지정된 Hugo 버전을 설치한다.

  2. website 리포지터리를 업데이트하지 않았다면, website/themes/docsy 디렉터리가 비어 있다. 테마의 로컬 복제본이 없으면 사이트를 빌드할 수 없다. website 테마를 업데이트하려면, 다음을 실행한다.

    git submodule update --init --recursive --depth 1
    
  3. 터미널에서, 쿠버네티스 website 리포지터리로 이동하여 Hugo 서버를 시작한다.

    cd <path_to_your_repo>/website
    hugo server --buildFuture
    
  4. 웹 브라우저에서 http://localhost:1313 으로 이동한다. Hugo는 변경 사항을 보고 필요에 따라 사이트를 다시 구축한다.

  5. 로컬의 Hugo 인스턴스를 중지하려면, 터미널로 돌아가서 Ctrl+C 를 입력하거나,     터미널 창을 닫는다.

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

아래 그림은 당신의 포크에서 K8s/website 저장소로 PR을 여는 단계를 보여 준다. 상세 사항은 아래에 등장한다.

flowchart LR subgraph first[ ] direction TB 1[1. K8s/website 저장소로 이동] --> 2[2. 'New Pull Request' 클릭] 2 --> 3[3. 'Compare across forks' 클릭] 3 --> 4[4. 'head repository' 드롭다운 메뉴에서
당신의 포크 선택] end subgraph second [ ] direction TB 5[5. 'compare' 드롭다운 메뉴에서
당신의 브랜치 선택] --> 6[6. 'Create Pull Request' 클릭] 6 --> 7[7. PR 본문에 상세 설명 기재] 7 --> 8[8. 'Create pull request' 클릭] 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 class 1,2,3,4,5,6,7,8 grey class first,second white

그림 - 당신의 포크에서 K8s/website 저장소로 PR을 여는 단계

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

  2. New Pull Request 를 선택한다.

  3. compare across forks 를 선택한다.

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

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

  6. Create Pull Request 를 선택한다. `. 풀 리퀘스트에 대한 설명을 추가한다.

    • Title(50자 이하): 변경 사항에 대한 의도를 요약한다.

    • Description: 변경 사항을 자세히 설명한다.

      • 관련된 GitHub 이슈가 있는 경우, Fixes #12345 또는 Closes #12345 를 설명에 포함한다. 이렇게 하면 GitHub의 자동화 기능이 PR을 병합한 후 언급된 이슈를 닫는다. 다른 관련된 PR이 있는 경우, 이들 PR도 연결한다.
      • 구체적인 내용에 대한 조언이 필요한 경우, 원하는 질문을 리뷰어가 생각해볼 수 있도록 설명에 포함한다.
  7. 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 테스트를 다시 실행한다.

리뷰어의 변경

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

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

    git fetch origin
    git rebase origin/<your-branch-name>
    
  2. 리베이스한 후, 포크에 새로운 변경 사항을 강제로 푸시한다.

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

충돌 병합 및 리베이스

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

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

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

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

    git push --force-with-lease origin <your-branch-name>
    
  2. kubernetes/websiteupstream/main 에 대한 변경 사항을 가져오고 브랜치를 리베이스한다.

    git fetch upstream
    git rebase upstream/main
    
  3. 리베이스의 결과를 검사한다.

    git status
    

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

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

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

    git add <filename>
    
  3. 리베이스를 계속한다.

    git rebase --continue
    
  4. 필요에 따라 2단계에서 5단계를 반복한다.

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

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

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

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

커밋 스쿼시하기

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

  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 단어를 바꾸면 리베이스가 완료되었을 때 커밋 상태가 변경된다.

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

  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 17d54e15ee Address feedback 2d875112ca 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을 제출할 때 가능한 한 상세하게 템플릿의 내용을 작성한다.

다음 내용

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

2 - 릴리스를 위한 기능 문서화

쿠버네티스의 각 주요 릴리스에는 문서화가 필요한 새로운 기능이 도입된다. 새로운 릴리스는 기존 기능 및 문서의 업데이트도 포함한다. (예: alpha에서 beta로의 기능 업그레이드)

일반적으로, 해당 기능을 담당하는 SIG는 해당 기능에 대한 초안 문서를 kubernetes/website 저장소의 적절한 개발 브랜치에 풀 리퀘스트로 제출하며, SIG Docs 팀의 누군가가 피드백을 제공하거나 초안을 직접 편집한다. 이 섹션은 두 그룹이 릴리스 과정에서 사용하는 브랜치 컨벤션과 프로세스를 다룬다.

블로그를 통해 기능을 발표하는 방법에 대해 알아보려면, 릴리스 후 커뮤니케이션을 읽어본다.

문서 기여자를 위한 안내

일반적으로, 문서 기여자는 릴리스를 위한 콘텐츠를 처음부터 작성하지는 않는다. 대신, 새로운 기능을 개발하는 SIG와 협업하여 초안 문서를 다듬고 릴리스 준비가 완료되도록 한다.

문서화하거나 협력하고 싶은 기능을 선택한 후, #sig-docs 슬랙 채널, 주간 SIG Docs 회의, 또는 해당 기능 SIG가 올린 PR에서 직접 문의한다. 승인을 받으면, 다른 사람의 PR에 커밋에서 설명한 방법 중 하나를 사용해 PR을 편집할 수 있다.

향후 기능 알아보기

향후 기능에 대해 알아보려면, 주간 SIG Release 회의에 참석한다. (다가오는 회의 일정은 커뮤니티 페이지에서 확인할 수 있다) 또한 kubernetes/sig-release 리포지토리의 릴리스별 문서를 모니터링 하면 된다. 각 릴리스는 /sig-release/tree/master/releases/ 디렉토리 아래에 하위 디렉토리를 가지고 있다. 이 하위 디렉토리에는 릴리스 일정, 릴리스 노트 초안 그리고 릴리스 팀 구성원 명단이 담긴 문서가 포함되어 있다.

릴리스 일정 문서에는 해당 릴리스와 관련된 다른 모든 문서, 회의, 회의록, 그리고 마일스톤에 대한 링크가 포함되어 있다. 또한, 릴리스의 목표와 일정, 이 릴리스에 적용되는 특수 프로세스에 대한 정보도 포함되어 포함되어 있다. 문서 하단에는 릴리스 관련 용어들이 정의되어 있다.

이 문서에는 기능 추적 시트에 대한 링크 또한 포함되어 있으며, 이는 이번 릴리스에 포함될 예정인 모든 신규 기능을 공식적으로 확인할 수 있는 방법이다.

릴리스 팀 문서는 각 릴리스 역할에 대한 책임자를 명시한다. 만약 특정 기능이나 질문에 대해 누구와 논의해야 할지 명확하지 않다면, 릴리스 회의에 참석하여 질문하거나, 릴리스 리드에게 연락하면 그들이 적절한 담당자에게 연결해 줄 수 있다.

릴리스 노트 초안은 특정 기능, 변경 사항, 사용 중단 예정 항목 등 이번 릴리스에 대한 내용을 파악하기에 좋은 자료이다. 다만, 이 내용은 릴리스 주기의 후반까지 확정되지 않으므로 참고 시 주의가 필요하다.

기능 추적 시트

쿠버네티스 릴리스 기능 추적 시트는 해당 릴리스에 포함될 예정인 각 기능을 나열한다. 각 항목에는 기능 이름, 해당 기능의 메인 GitHub 이슈 링크, 안정성 단계(알파, 베타, 스테이블), SIG 및 해당 기능을 구현하는 담당자, 문서화가 필요한지 여부, 기능의 릴리스 노트 초안, 그리고 해당 기능이 병합되었는지 여부가 포함된다. 다음 사항을 유의한다.

  • 베타 및 스테이블 기능은 일반적으로 알파 기능보다 문서화 우선순위가 높다.
  • 아직 병합되지 않았거나, PR 상에서 최소한 기능이 완성된 것으로 간주되지 않은 기능은 테스트하기 어렵고, 따라서 문서화도 어렵다.
  • 기능이 문서화가 필요한지 여부는 수동으로 판단해야 한다. 문서화 필요 여부로 표시되지 않은 기능이라 하더라도 문서화가 필요할 수 있다.

개발자 또는 다른 SIG 구성원을 위한 안내

이 섹션은 쿠버네티스의 다른 SIG 구성원들이 릴리스를 위해 새로운 기능을 문서화하는 데 관련된 정보를 제공한다.

쿠버네티스의 새로운 기능을 개발 중인 SIG의 구성원이라면, 해당 기능이 릴리스 시점에 적시에 문서화되도록 SIG Docs와 협력해야 한다. 기능 추적 스프레드시트를 확인하거나, 쿠버네티스 Slack의 #sig-release 채널에서 일정 세부 사항과 마감일을 확인한다.

임시 PR 열기

  1. kubernetes/website 저장소의 dev-1.35 브랜치를 대상으로 나중에 수정할 예정인 간단한 커밋을 포함한 초안 PR을 연다. 초안 PR을 생성하려면, Create Pull Request 드롭다운 메뉴에서 Create Draft Pull Request를 선택한 다음, Draft Pull Request 버튼을 클릭한다.
  2. PR 설명란에 kubernetes/kubernetes PR과 kubernetes/enhancements 이슈에 대한 링크를 추가한다.
  3. 관련 kubernetes/enhancements 이슈에 해당 PR 링크를 포함한 댓글을 남겨, 이 릴리스를 관리하는 문서 담당자에게 기능 문서가 준비 중이며 릴리스에 반영해야 함을 알린다.

기능에 대해 문서 변경이 필요하지 않다면, #sig-release 슬랙 채널에 해당 내용을 알려 sig-release 팀이 이를 인지할 수 있도록 한다. 기능에 문서화가 필요하지만 PR이 생성되지 않은 경우, 해당 기능은 마일스톤에서 제외될 수 있다.

리뷰를 위한 PR 준비

준비가 되면, 기능 문서와 변경 사항을 임시 PR에 입력하고 PR의 상태를 초안(draft)에서 ready for review 상태로 변경한다. 풀 리퀘스트를 검토 가능 상태로 표시하려면, 머지 박스로 이동한 후 Ready for review 버튼을 클릭한다.

기능을 설명하고 사용 방법을 설명하는 데 최선을 다한다. 문서 구조화에 도움이 필요하면 #sig-docs 슬랙 채널에 문의한다.

콘텐츠 작성을 마치면, 해당 기능에 배정된 문서 담당자가 이를 검토한다. 기술적인 정확성을 보장하기 위해, 해당 기능을 담당하는 SIG에서 기술 검토가 필요할 수 있다. 담당자의 제안을 활용하여 콘텐츠를 릴리스가 가능한 상태로 만든다.

기능에 문서화가 필요한지만 첫 번째 초안 콘텐츠가 제출되지 않은 경우, 해당 기능은 마일스톤에서 제외될 수 있다.

기능 게이트

기능이 알파 또는 베타 단계이며 기능 게이트를 통해 활성화되는 경우, 해당 기능에 대한 기능 게이트 파일을 content/en/docs/reference/command-line-tools-reference/feature-gates/ 디렉토리 안에 추가해야 한다. 파일 이름은 해당 기능 게이트의 이름에 .md 확장자를 추가한 형태로 지정해야 한다. 동일한 디렉토리에 이미 존재하는 다른 파일을 참고하여 당신의 파일 구조를 결정할 수 있다. 일반적으로 단락 하나만으로도 충분하며, 더 긴 설명이 필요한 경우 다른 곳에 문서를 추가하고 해당 링크를 포함한다.

또한, 당신의 기능 게이트가 알파 또는 베타 기능을 위한 기능 게이트 표에 표시되도록 하려면, 당신의 마크다운 설명 파일의 front matter (문서 헤더)에 다음 정보를 포함해야 한다.

stages:
  - stage: <alpha/beta/stable/deprecated>  # 기능 게이트의 개발 단계를 지정한다
    defaultValue: <true or false>          # 기본적으로 활성화되어 있다면 true, 아니라면 false로 설정한다
    fromVersion: <Version>                 # 기능 게이트가 사용 가능한 최소 버전을 입력한다
    toVersion: <Version>                   # (선택 사항) 기능 게이트가 사용 가능한 마지막 버전을 입력한다

새로운 기능 게이트를 추가하는 경우, 해당 기능 게이트에 대한 별도의 설명도 필요하다. content/en/docs/reference/command-line-tools-reference/feature-gates/ 디렉토리 안에 새로운 마크다운 파일을 생성한다 (다른 파일들의 템플릿을 참고하면 된다).

기능 게이트를 비활성화 상태에서 활성화 상태로 변경하는 경우, (기능 게이트 목록 외에도) 다른 문서도 수정해야 할 수 있다. "exampleSetting 필드는 베타 단계이며 기본적으로 비활성화되어 있다." 와 같은 문구가 문서에 남아 있는지 주의 깊게 살펴본다. 이 기능은 ProcessExampleThings 기능 게이트를 활성화하면 사용할 수 있다.

기능이 일반 공개(GA) 되었거나 사용 중단(deprecated)된 경우, 설명 파일의 stages 블록에 추가적인 stage 항목을 포함힌다. 알파 및 베타 단계는 그대로 유지되어야 한다. 이 단계는 해당 기능 게이트를 알파 또는 베타 기능 게이트 표에서 승급 또는 사용 중단된 기능 게이트 표로 전환 한다. 예를 들면 다음과 같다.

stages:
  - stage: alpha 
    defaultValue: false
    fromVersion: "1.12"
    toVersion: "1.12"
  - stage: beta 
    defaultValue: true
    fromVersion: "1.13"
  # 이전 단계에 `toVersion` 항목을 추가한다
    toVersion: "1.18"
  # 기존 단계에 'stable' 단계 블록을 추가한다
  - stage: stable
    defaultValue: true
    fromVersion: "1.19"
    toVersion: "1.27"

결국 쿠버네티스는 해당 기능 게이트를 아예 포함하지 않게 될 것이다. 기능 게이트가 제거되었음을 명시하려면, 해당 설명 파일의 front matter(문서 헤더)에 removed: true를 추가한다. 이렇게 변경하면 해당 기능 게이트 정보는 승급 또는 사용 중단된 기능 게이트 섹션에서 제거된 기능 게이트라는 별도의 페이지로 이동하며, 그 설명도 함께 포함된다.

모든 PR이 검토되고 병합 준비 완료

릴리스 마감 기한까지 당신의 PR이 아직 dev-1.35 브랜치에 병합되지 않았다면, 이번 릴리스를 관리하는 문서 담당자와 협력하여 마감 기한 내에 병합될 수 있도록 한다. 기능에 문서화가 필요하지만 문서가 준비되지 않았다면 해당 기능은 마일스톤에서 제외될 수 있다.

3 - 사례 연구 제출

사례 연구는 조직들이 쿠버네티스를 활용해 실제 문제를 해결하는 방법을 보여준다. 쿠버네티스 마케팅 팀과 CNCF 구성원들은 모든 사례 연구에 대해 여러분과 협력한다.

사례 연구는 승인되기 전에 철저한 검토가 필요하다.

사례 연구 제출하기

기존 사례 연구의 소스를 살펴본다.

사례 연구 가이드라인을 참조하고 가이드라인에 명시된 대로 요청을 제출한다.