SIG Docsへの参加
SIG Docsは、Kubernetesプロジェクト内の
special interest groupsの1つであり、
Kubernetes全体のドキュメントの作成、更新、および保守に重点を置いています。
SIGの詳細については、SIG DocsのGithubリポジトリを参照してください。
SIG Docsは、すべての寄稿者からのコンテンツとレビューを歓迎します。
誰でもPull Request(PR)を開くことができ、コンテンツに関するissueを提出したり、進行中のPull Requestにコメントしたりできます。
あなたは、memberや、
reviewer、
approverになることもできます。
これらの役割にはより多くのアクセスが必要であり、変更を承認およびコミットするための特定の責任が伴います。
Kubernetesコミュニティ内でメンバーシップがどのように機能するかについての詳細は、
community-membership
をご覧ください。
このドキュメントの残りの部分では、kubernetesの中で最も広く公開されている
Kubernetesのウェブサイトとドキュメントの管理を担当しているSIG Docsの中で、これらの役割がどのように機能するのかを概説します。
SIG Docs chairperson
SIG Docsを含む各SIGは、議長として機能する1人以上のSIGメンバーを選択します。
これらは、SIGDocsとKubernetes organizationの他の部分との連絡先です。
それらには、Kubernetesプロジェクト全体の構造と、SIG Docsがその中でどのように機能するかについての広範な知識が必要です。
現在のchairpersonのリストについては、
Leadership
を参照してください。
SIG Docs teamsと自動化
SIG Docsの自動化は、GitHub teamsとOWNERSファイルの2つの異なるメカニズムに依存しています。
GitHub teams
GitHubには、二つのSIG Docs
teams
カテゴリがあります:
@sig-docs-{language}-ownersは承認者かつリードです。@sig-docs-{language}-reviews はレビュアーです。
それぞれをGitHubコメントの@nameで参照して、そのグループの全員とコミュニケーションできます。
ProwチームとGitHub teamsが完全に一致せずに重複する場合があります。
問題の割り当て、Pull Request、およびPR承認のサポートのために、自動化ではOWNERSファイルからの情報を使用します。
OWNERSファイルとfront-matter
Kubernetesプロジェクトは、GitHubのissueとPull Requestに関連する自動化のためにprowと呼ばれる自動化ツールを使用します。
Kubernetes Webサイトリポジトリ
は、2つのprowプラグインを使用します：
これらの2つのプラグインはkubernetes.websiteのGithubリポジトリのトップレベルにある
OWNERSファイルと、
OWNERS_ALIASESファイルを使用して、
リポジトリ内でのprowの動作を制御します。
OWNERSファイルには、SIG Docsのレビュー担当者および承認者であるユーザーのリストが含まれています。
OWNERSファイルはサブディレクトリに存在することもでき、そのサブディレクトリとその子孫のファイルのレビュー担当者または承認者として機能できるユーザーを上書きできます。
一般的なOWNERSファイルの詳細については、
OWNERSを参照してください。
さらに、個々のMarkdownファイルは、個々のGitHubユーザー名またはGitHubグループを一覧表示することにより、そのfront-matterでレビュー担当者と承認者を一覧表示できます。
OWNERSファイルとMarkdownファイルのfront-matterの組み合わせにより、PRの技術的および編集上のレビューを誰に依頼するかについてPRの所有者が自動化システムから得るアドバイスが決まります。
マージの仕組み
Pull Requestがコンテンツの公開に使用されるブランチにマージされると、そのコンテンツは https://kubernetes.io に公開されます。
公開されたコンテンツの品質を高くするために、Pull RequestのマージはSIG Docsの承認者に限定しています。仕組みは次のとおりです。
- Pull Requestに
lgtmラベルとapproveラベルの両方があり、holdラベルがなく、すべてのテストに合格すると、Pull Requestは自動的にマージされます。 - Kubernetes organizationのメンバーとSIG Docsの承認者はコメントを追加して、特定のPull Requestが自動的にマージされないようにすることができます(
/holdコメントを追加するか、/lgtmコメントを保留します)。 - Kubernetesメンバーは誰でも、
/lgtmコメントを追加することでlgtmラベルを追加できます。 /approveコメントを追加してPull Requestをマージできるのは、SIG Docsの承認者だけです。一部の承認者は、PR WranglerやSIG Docsのchairpersonなど、追加の特定の役割も実行します。
次の項目
Kubernetesドキュメントへの貢献の詳細については、以下を参照してください：
1 - ロールと責任
誰もがKubernetesに貢献することができます。
SIG Docs へのコントリビューションが増えると、コミュニティ内で異なるレベルのメンバーシップに申請することができます。
これらの役割により、コミュニティ内でより多くの責任を担うことができます。
各役割にはより多くの時間とコミットメントが必要です。
役割は以下の通りです:
- Anyone: Kubernetesドキュメントへの定期的なコントリビューター
- Member: Issueの割り当てとトリアージができ、Pull Requestに対する非公式なレビューができる
- Reviewer: ドキュメントのPull Requestのレビューをリードし、変更の品質を保証する
- Approver: ドキュメントのレビューをリードし、変更をマージできる
Anyone
GitHubのアカウントを持っている人なら誰もがKubernetesに貢献することができます。
SIG Docs はすべての新たなコントリビューターを歓迎します。
誰もが以下のことをできます:
CLA に署名した後は、誰もが以下のことをできます:
- 既存のコンテンツを改善するためのPull Requestを開く、新しいコンテンツを追加する、ブログ記事やケーススタディを書く
- 図表やグラフィックアセット、埋め込み可能なスクリーンキャストやビデオを作成する
詳細については、新しいコンテンツの貢献を参照してください。
Member
Memberは、kubernetes/websiteに複数のPull Requestを作成した人です。
MemberはKubernetes GitHub organizationの一員です。
Memberは以下のことをできます:
Anyoneに列挙されているすべてのことを行う
/lgtmコメントを使用して、Pull RequestにLGTM (looks good to me)ラベルを追加する
備考:
/lgtmを使用すると、自動化がトリガーされます。
非公式に承認したい場合は、"LGTM"とコメントするだけでも大丈夫です！/holdコメントを使用して、Pull Requestのマージをブロックする
/assignコメントを使用して、Pull RequestにReviewerを割り当てる
Pull Requestに非公式なレビューを提供する
自動化を使用してIssueをトリアージし、分類する
新機能をドキュメント化する
Memberになる
少なくとも5つの実質的なPull Requestを作成し、その他の要件を満たした後に以下のようにしてMemberになることができます:
2人のReviewerまたはApproverにあなたのメンバーシップをスポンサーしてもらいます。
Slackの#sig-docsチャンネルやSIG Docsのメーリングリストでスポンサーを依頼してください。
備考:
個別のSIG Docsメンバーに直接メールやSlackのダイレクトメッセージを送らないでください。
また申請する前にスポンサーを依頼する必要があります。kubernetes/orgリポジトリにIssueを作成します。Organization Membership Requestのissueテンプレートを使用してください。
スポンサーにGitHub Issueのことを知らせます。以下の方法があります:
Issue内でGitHubユーザー名に言及する（@<GitHub-username>）
Slackやメールを使ってIssueのリンクを送る
スポンサーは+1の投票でリクエストを承認します。
スポンサーがリクエストを承認すると、Kubernetes GitHubの管理者があなたをメンバーとして追加します。
おめでとうございます！
メンバーシップリクエストが承認されない場合はフィードバックを受け取ります。
フィードバックに対応した後、再度申請してください。
メールアカウントでKubernetes GitHub organizationの招待を受け入れます。
備考:
GitHubはアカウントのデフォルトメールアドレスに招待を送信します。
Reviewer
ReviewerはオープンなPull Requestのレビューを担当します。
Memberのフィードバックとは異なり、PRを作成した人はReviewerのフィードバックに対応する必要があります。
Reviewerは@kubernetes/sig-docs-{language}-reviews GitHubチームのメンバーです。
Reviewerは以下のことをできます:
AnyoneおよびMemberに列挙されているすべてのことを行う
Pull Requestをレビューし、拘束力のあるフィードバックを提供する
備考:
拘束力のないフィードバックを提供する場合、コメントの前に"Optionally: "などのフレーズを付けてください。コード内のユーザー向けの文字列を編集する
コードコメントを改善する
SIG DocsのReviewer、あるいは特定の領域に関するドキュメントのReviewerになることができます。
Pull RequestへのReviewerの割り当て
自動化により、すべてのPull RequestにReviewerが割り当てられます。
特定の人物にレビューを依頼するには、/assign [@_github_handle]とコメントします。
割り当てられたReviewerがPRにコメントしていない場合、他のReviewerが代わりにレビューできます。
また、必要に応じて技術的なReviewerを割り当てることもできます。
/lgtmの使用
LGTMは"Looks good to me"の略で、Pull Requestが技術的に正確でマージの準備が整っていることを示します。
すべてのPRには、マージするためにReviewerからの/lgtmコメントとApproverからの/approveコメントが必要です。
Reviewerからの/lgtmコメントは拘束力があり、自動化によりlgtmラベルが追加されます。
Reviewerになる
要件を満たすと、SIG DocsのReviewerになることができます。他のSIGのReviewerは、SIG DocsでのReviewerステータスを別途申請する必要があります。
申請方法は以下の通りです:
kubernetes/websiteリポジトリのOWNERS_ALIASESファイルのセクションに、GitHubユーザー名を追加するPull Requestを開きます。
備考:
どこに追加すればよいかわからない場合は、sig-docs-en-reviewsに追加してください。
訳注: sig-docs-en-reviewsは英語版のReviewerチームです。日本語ローカライゼーションのReviewerチームに参加する場合は、sig-docs-ja-reviewsに追加してください。
PRを1人以上のSIG Docs Approverに割り当てます(ユーザー名はsig-docs-{language}-ownersに記載されています)。
承認されると、SIG Docsのリードが適切なGitHubチームに追加します。
追加されると、k8s-ci-robotが新しいPull RequestのReviewerとしてあなたを割り当て、提案します。
Approver
ApproverはPull Requestをレビューし、マージするために承認します。
Approverは@kubernetes/sig-docs-{language}-owners GitHubチームのメンバーです。
Approverは以下のことをできます:
- Anyone、Member、およびReviewerに列挙されているすべてのことを行う
/approveコメントを使用してPull Requestを承認およびマージすることで、コントリビューターのコンテンツを公開する- スタイルガイドの改善を提案する
- ドキュメントテストの改善を提案する
- Kubernetesのウェブサイトや他のツールの改善を提案する
PRに既に/lgtmが付いている場合、またはApprover自身が/lgtmコメントを付けた場合、PRは自動的にマージされます。
SIG DocsのApproverは、追加の技術的なレビューが不要な変更にのみ/lgtmを付けるべきです。
Pull Requestの承認
ApproverとSIG DocsのリードだけがPull Requestをwebsiteリポジトリにマージすることができます。
これには一定の責任が伴います。
Approverは/approveコマンドを使用して、PRをリポジトリにマージできます。
警告:
不注意なマージはサイトを壊す可能性があるため、マージする際には慎重に行ってください。提案された変更がドキュメントコンテンツガイドに準拠していることを確認してください。
もし疑問がある場合や何か不明な点がある場合は、遠慮なく追加のレビューを依頼してください。
PRを/approveする前に、Netlifyのテストに通っていることを確認してください。
承認する前に、PRのNetlifyのページプレビューをクリックして内容が正しいことを確認してください。
週ごとのローテーションであるPR Wranglerローテーションスケジュールに参加してください。SIG DocsはすべてのApproverにこのローテーションへの参加を期待しています。詳細についてはPR wranglersを参照してください。
Approverになる
要件を満たすと、SIG DocsのApproverになることができます。
他のSIGのApproverは、SIG DocsでのApproverステータスを別途申請する必要があります。
申請方法は以下の通りです:
kubernetes/websiteリポジトリのOWNERS_ALIASESファイルのセクションに、自分自身を追加するPull Requestを開きます。
備考:
どこに追加すればよいかわからない場合は、`sig-docs-en-owners`に追加してください。
訳注: `sig-docs-en-owners`は英語版のApproverチームです。
日本語ローカライゼーションのApproverチームに参加する場合は、`sig-docs-ja-owners`に追加してください。
PRを1人以上の現在のSIG Docs Approversに割り当てます。
承認されると、SIG Docsのリードが適切なGitHubチームに追加します。
追加されると、k8s-ci-robotが新しいPull RequestのReviewerとしてあなたを割り当て、提案します。
次の項目