approverとreviewer向けのレビュー

SIG DocsのReviewer(レビュアー)とApprover(承認者)は、変更をレビューする時にいくつか追加の作業を行います。

毎週、docsのメンバーの特定のapproverのボランティアは、pull requestのトリアージとレビューを担当します。この担当者は、その週の「PR Wrangler(PRの世話人)」と呼ばれます。詳しい情報は、PR Wrangler schedulerを参照してください。PR Wranglerになるには、週次のSIG Docsミーティングに参加し、ボランティアをします。もしその週にスケジュールされていなくても、活発なレビューが行われていないpull request(PR)をレビューすることは問題ありません。

このローテーションに加えて、変更されたファイルのオーナーに基づいて、botがPRにreviewerとapproverを割り当てます。

PRをレビューする

KubernetesのドキュメントはKubernetesコードレビュープロセスに従います。

pull requestのレビューに書かれているすべてのことが適用されますが、ReviewerとApproverはそれに加えて次のことも行います。

• 必要に応じて、/assignProwコマンドを使用して、特定のreviewerにPRを割り当てる。これは、コードのコントリビューターからの技術的なレビューが必要な場合には特に重要です。

  備考: 技術的なレビューを行える人物を知るには、Markdownファイル上部にあるfront-matterのreviewersフィールドを確認してください。

• PRがコンテンツおよびスタイルのガイドに従っていることを確認してください。ガイドに従っていない場合は、ガイドの関連する部分にリンクを作者に示してください。

• PRの作者に変更を提案できるときは、GitHubのRequest Changes(変更をリクエスト)オプションを利用してください。

• 提案したことが反映されたら、/approveや/lgtmコマンドを使用して、GitHubのレビューステータスを変更してください。

他の作者のPRにコミットを追加する

PRにコメントを残すのは助けになりますが、まれに他の作者のPRに代わりにコミットを追加する必要がある場合があります。

あなたが明示的に作者から頼まれたり、長い間放置されたPRを蘇らせるような場合でない限り、他の作者のPRを「乗っ取る」ようなことはしないでください。短期的に見ればそのほうが短時間で終わるかもしれませんが、そのようなことをするとその人が貢献するチャンスを奪ってしまうことになります。

あなたが取る方法は、編集する必要のあるファイルがすでにPRのスコープに入っているか、あるいはPRがまだ触れていないファイルであるかによって変わります。

以下のいずれかが当てはまる場合、他の作者のPRにあなたがコミットを追加することはできません。

• PRの作者が自分のブランチを直接https://github.com/kubernetes/website/リポジトリにpushした場合。この場合、pushアクセス権限を持つreviewerしか他のユーザーのPRにコミットを追加することはできません。

  備考: 次回PRを作成するとき、自分のブランチを自分のforkに対してpushするように作者に促してください。

• PRの作者が明示的にapproverからの編集を禁止している場合。

レビュー向けのProwコマンド

Prowは、pull request(PR)に対してジョブを実行するKubernetesベースのCI/CDシステムです。Prowは、Kubernetes organization全体でchatbotスタイルのコマンドを利用してGitHub actionsを扱えるようにします。たとえば、ラベルの追加と削除、issueのclose、approverの割り当てなどが行なえます。Prowコマンドは、GitHubのコメントに/<command-name>という形式で入力します。

reviewerとapproverが最もよく使うprowコマンドには、以下のようなものがあります。

Prow commands for reviewing

Prowコマンド	Roleの制限	説明
/lgtm	Organizationメンバー	PRのレビューが完了し、変更に納得したことを知らせる。
/approve	Approver	PRをマージすることを承認する。
/assign	誰でも	PRのレビューまたは承認するひとを割り当てる。
/close	Organizationメンバー	issueまたはPRをcloseする。
/hold	誰でも	do-not-merge/holdラベルを追加して、自動的にマージできないPRであることを示す。
/hold cancel	誰でも	do-not-merge/holdラベルを削除する。

PRで利用できるすべてのコマンドを確認するには、Prowコマンドリファレンスを参照してください。

issueのトリアージとカテゴリー分類

一般に、SIG DocsはKubernetes issue triageのプロセスに従い、同じラベルを使用しています。

このGitHub issueのフィルターは、トリアージが必要な可能性があるissueを表示します。

issueをトリアージする

1. issueを検証する

• issueがドキュメントのウェブサイトに関係するものであることを確かめる。質問に答えたりリソースの場所を報告者に教えることですぐに閉じられるissueもあります。詳しくは、サポートリクエストまたはコードのバグレポートのセクションを読んでください。
• issueにメリットがあるかどうか評価する。
• issueに行動を取るのに十分な詳細情報がない場合や、テンプレートが十分埋められていない場合は、triage/needs-informationラベルを追加する。
• lifecycle/staleとtriage/needs-informationの両方のラベルがあるときは、issueをcloseする。

2. 優先度(priority)ラベルを追加する(issueトリアージガイドラインは、priorityラベルについて詳しく定義しています。)

issueのラベル

ラベル	説明
priority/critical-urgent	今すぐに作業する。
priority/important-soon	3ヶ月以内に取り組む。
priority/important-longterm	6ヶ月以内に取り組む。
priority/backlog	無期限に延期可能。リソースに余裕がある時に取り組む。
priority/awaiting-more-evidence	よいissueの可能性があるissueを見失わないようにするためのプレースホルダー。
helpまたはgood first issue	KubernetesまたはSIG Docsでほとんど経験がない人に適したissue。より詳しい情報は、Help WantedとGood First Issueラベルを読んでください。

あなたの裁量で、issueのオーナーシップを取り、issueに対するPRを提出してください(簡単なissueや、自分がすでに行った作業に関連するissueである場合は特に)。

issueのトリアージについて質問があるときは、Slackの#sig-docsかkubernetes-sig-docs mailing listで質問してください。

issueラベルの追加と削除

ラベルを追加するには、以下のいずれかの形式でコメントします。

• /<label-to-add>(たとえば、/good-first-issue)
• /<label-category> <label-to-add>(たとえば、/triage needs-informationや/language ja)

ラベルを削除するには、以下のいずれかの形式でコメントします。

• /remove-<label-to-remove>(たとえば、/remove-help)
• /remove-<label-category> <label-to-remove>(たとえば、/remove-triage needs-information)

いずれの場合でも、ラベルは既存のものでなければなりません。存在しないラベルを追加しようとした場合、コマンドは無視されます。

すべてのラベル一覧は、websiteリポジトリーのラベルセクションで確認できます。SIG Docsですべてのラベルが使われているわけではありません。

issueのライフサイクルに関するラベル

issueは一般にopen後に短期間でcloseされます。しかし、issueがopenされた後にアクティブでなくなったり、issueが90日以上openのままである場合もあります。

issueのライブラリに関するラベル

ラベル	説明
lifecycle/stale	90日間活動がない場合、issueは自動的にstaleとラベル付けされます。/remove-lifecycle staleコマンドを使って手動でlifecycleをリバートしない限り、issueは自動的にcloseされます。
lifecycle/frozen	このラベルが付けられたissueは、90日間活動がなくてもstaleになりません。priority/important-longtermラベルを付けたissueなど、90日以上openにしておく必要があるissueには、このラベルを手動で追加します。

特別な種類のissueに対処する

SIG Docsでは、対処方法をドキュメントに書いても良いくらい頻繁に、以下のような種類のissueに出会います。

重服したissue

1つの問題に対して1つ以上のissueがopenしている場合、1つのissueに統合します。あなたはどちらのissueをopenにしておくか(あるいは新しいissueを作成するか)を決断して、すべての関連する情報を移動し、関連するすべてのissueにリンクしなければなりません。最後に、同じ問題について書かれたすべての他のissueにtriage/duplicateラベルを付けて、それらをcloseします。作業対象のissueを1つだけにすることで、混乱を減らし、同じ問題に対して作業が重複することを避けられます。

リンク切れに関するissue

リンク切れのissueがAPIまたはkubectlのドキュメントにあるものは、問題が完全に理解されるまでは/priority critical-urgentを割り当ててください。その他のすべてのリンク切れに関するissueには、手動で修正が必要であるため、/priority important-longtermを付けます。

Blogに関するissue

Kubernetes Blogのエントリーは時間が経つと情報が古くなるものだと考えています。そのため、ブログのエントリーは1年以内のものだけをメンテナンスします。1年以上前のブログエントリーに関するissueは修正せずにcloseします。

サポートリクエストまたはコードのバグレポート

一部のドキュメントのissueは、実際には元になっているコードの問題や、何か(たとえば、チュートリアル)がうまく動かないときにサポートをリクエストするものです。ドキュメントに関係のない問題は、kind/supportラベルを付け、サポートチャンネル(SlackやStack Overflowなど)へ報告者を導くコメントをして、もし関連があれば機能のバグに対するissueを報告するリポジトリ(kubernetes/kubernetesは始めるのに最適な場所です)を教えて、closeします。

サポートリクエストに対する返答の例を示します。(リクエストを行う際は英語で行うことが想定されるため、英文とその日本語訳を記載しています)

This issue sounds more like a request for support and less
like an issue specifically for docs. I encourage you to bring
your question to the `#kubernetes-users` channel in
[Kubernetes slack](https://slack.k8s.io/). You can also search
resources like
[Stack Overflow](https://stackoverflow.com/questions/tagged/kubernetes)
for answers to similar questions.

You can also open issues for Kubernetes functionality in
https://github.com/kubernetes/kubernetes.

If this is a documentation issue, please re-open this issue.

このissueは特定のドキュメントに関するissueではなく、サポートリクエストのようです。
Kubernetesに関する質問については、[Kubernetes slack](https://slack.k8s.io/)の
`#kubernetes-users`チャンネルに投稿することをおすすめします。同様の質問に対する回答を
[Stack Overflow](https://stackoverflow.com/questions/tagged/kubernetes)などの
リソースで検索することもできます。

Kubernetesの機能に関するissueについては、https://github.com/kubernetes/kubernetes
でissueを作成できます。

もしこれがドキュメントに関するissueの場合、このissueを再びopenしてください。

コードのバグに対する返答の例を示します。

This sounds more like an issue with the code than an issue with
the documentation. Please open an issue at
https://github.com/kubernetes/kubernetes/issues.

If this is a documentation issue, please re-open this issue.

こちらのissueは、ドキュメントではなくコードに関係するissueのようです。
https://github.com/kubernetes/kubernetes/issues でissueを作成してください。

もしこれがドキュメントに関するissueの場合、このissueを再びopenしてください。