変更のレビュー

このセクションでは、コンテンツのレビュー方法について説明します。

1 - Pull Requestのレビュー

ドキュメントのPull Requestは誰でもレビューすることができます。Kubernetesのwebsiteリポジトリでpull requestsのセクションに移動し、open状態のPull Requestを確認してください。

ドキュメントのPull Requestのレビューは、Kubernetesコミュニティに自分を知ってもらうためのよい方法の1つです。コードベースについて学んだり、他のコントリビューターとの信頼関係を築く助けともなるはずです。

レビューを行う前には、以下のことを理解しておくとよいでしょう。

• コンテンツガイドとスタイルガイドを読んで、有益なコメントを残せるようにする。
• Kubernetesのドキュメントコミュニティにおける役割と責任の違いを理解する。

はじめる前に

レビューを始める前に、以下のことを心に留めてください。

• CNCFの行動規範を読み、いかなる時にも行動規範にしたがって行動するようにする。
• 礼儀正しく、思いやりを持ち、助け合う気持ちを持つ。
• 変更点だけでなく、PRのポジティブな側面についてもコメントする。
• 相手の気持ちに共感して、自分のレビューが相手にどのように受け取られるのかをよく意識する。
• 相手の善意を前提として、疑問点を明確にする質問をする。
• 経験を積んだコントリビューターの場合、コンテンツに大幅な変更が必要な作業を行う新規のコントリビューターとペアを組んで取り組むことを考える。

レビューのプロセス

一般に、コンテンツや文体に対するPull Requestは、英語でレビューを行います。図1は、レビュープロセスについて手順の概要を示しています。 各ステップの詳細は次のとおりです。

(訳注:SIG Docs jaでは、日本語でも対応しています。日本語の翻訳に対するレビューは、日本語でも構いません。ただし、Pull Requestの作成者や他のコントリビューターが必ずしも日本語を理解できるとは限りませんので、注意して発言してください。)

図1. レビュープロセスの手順

1. https://github.com/kubernetes/website/pullsに移動します。Kubernetesのウェブサイトとドキュメントに対するopen状態のPull Request一覧が表示されます。

2. open状態のPRに、以下に示すラベルを1つ以上使って絞り込みます。

   • cncf-cla: yes (推奨): CLAにサインしていないコントリビューターが提出したPRはマージできません。詳しい情報は、CLAの署名を読んでください。
   • language/en (推奨): 英語のPRだけに絞り込みます。
   • size/<size>: 特定の大きさのPRだけに絞り込みます。レビューを始めたばかりの人は、小さなPRから始めてください。

   さらに、PRがwork in progressとしてマークされていないことも確認してください。work in progressラベルの付いたPRは、まだレビューの準備ができていない状態です。

3. レビューするPRを選んだら、以下のことを行い、変更点について理解します。

   • PRの説明を読み、行われた変更について理解し、関連するissueがあればそれも読みます。
   • 他のレビュアのコメントがあれば読みます。
   • Files changedタブをクリックし、変更されたファイルと行を確認します。
   • Conversationタブの下にあるPRのbuild checkセクションまでスクロールし、Netlifyのプレビュービルドで変更点をプレビューします。これはスクリーンショットです(これは、GitHubのデスクトップサイトを見せています。タブレットやスマートフォンデバイスでレビューしている場合は、GitHubウェブのUIは少し異なります):

     

     プレビューを開くには、チェックリストのdeploy/netlify行のDetailsリンクをクリックします。

4. Files changedタブに移動してレビューを始めます。

   1. コメントしたい場合は行の横の+マークをクリックします。

   2. その行に関するコメントを書き、Add single comment(1つのコメントだけを残したい場合)またはStart a review(複数のコメントを行いたい場合)のいずれかをクリックします。

   3. コメントをすべて書いたら、ページ上部のReview changesをクリックします。ここでは、レビューの要約を追加できます(コントリビューターにポジティブなコメントも書きましょう！)。常に「Comment」を使用してください。

      • レビューの終了時、「Request changes」ボタンをクリックしないでください。さらに変更される前にマージされるのをブロックしたい場合、「/hold」コメントを残すことができます。Holdを設定する理由を説明し、必要に応じて、自分や他のレビューアがHoldを解除できる条件を指定してください。
      • レビューの終了時、「Approve」ボタンをクリックしないでください。大抵の場合、「/approve」コメントを残すことが推奨されます。

レビューのチェックリスト

レビューするときは、最初に以下の点を確認してみてください。

言語と文法

• 言語や文法に明らかな間違いはないですか？ もっとよい言い方はないですか？
  • 作成者が変更している箇所の用語や文法に注目してください。作成者がページ全体の変更を目的として明確にしていない限り、そのページのすべての問題を修正する義務はありません。
  • 既存のページを変更するPRである場合、変更されている箇所に注目してレビューしてください。その変更されたコンテンツは、技術的および編集の正確性についてレビューしてください。PRの作成者が対処しようとしている内容と直接関係のない間違いを見つけた場合、それは別のIssueとして扱うべきです(既存のIssueが無いことを確認してください)。
  • コンテンツを移動するPull Requestに注意してください。作成者がページの名前を変更したり、2つのページを結合したりする場合、通常、私たち(Kubernetes SIG Docs)は、その移動されたコンテンツ内で見つけられるすべての文法やスペルの間違いを修正することを作成者に要求することを避けています。
• もっと簡単な単語に置き換えられる複雑な単語や古い単語はありませんか？
• 使われている単語や専門用語や言い回しで差別的ではない別の言葉に置き換えられるものはありませんか？
• 言葉選びや大文字の使い方はstyle guideに従っていますか？
• もっと短くしたり単純な文に書き換えられる長い文はありませんか？
• 箇条書きやテーブルでもっとわかりやすく表現できる長いパラグラフはありませんか？

コンテンツ

• 同様のコンテンツがKubernetesのサイト上のどこかに存在しませんか？
• コンテンツが外部サイト、特定のベンダー、オープンソースではないドキュメントなどに過剰にリンクを張っていませんか？

ウェブサイト

• PRはページ名、slug/alias、アンカーリンクの変更や削除をしていますか？ その場合、このPRの変更の結果、リンク切れは発生しませんか？ ページ名を変更してslugはそのままにするなど、他の選択肢はありませんか？
• PRは新しいページを作成するものですか？ その場合、次の点に注意してください。
  • ページは正しいpage content typeと関係するHugoのshortcodeを使用していますか？
  • セクションの横のナビゲーションにページは正しく表示されますか(または表示されませんか)？
  • ページはDocs Homeに一覧されますか？
• Netlifyのプレビューで変更は確認できますか？ 特にリスト、コードブロック、テーブル、備考、画像などに注意してください。

その他

• 些細な編集に注意してください。些細な編集だと思われる変更を見つけた場合は、そのポリシーを指摘してください (それが本当に改善である場合は、変更を受け入れても問題ありません)。
• 空白の修正を行っている作成者には、PRの最初のコミットでそれを行い、その後に他の変更を加えるよう促してください。これにより、マージとレビューの両方が容易になります。特に、大量の空白文字の整理と共に1回のコミットで発生する些細な変更に注意してください(もしそれを見つけたら、作成者に修正を促してください)。

レビュアーが誤字や不適切な空白など、PRの本質でない小さな問題を発見した場合は、コメントの先頭にnit:を付けてください。これにより、作成者はこのフィードバックが重要でないことを知ることができます。

Pull Requestの承認を検討する際、残りのすべてのフィードバックがnitとしてマークされていれば、残っていたとしてもPRをマージできます。その場合、残っているnitに関するIssueをオープンすると役立つことがよくあります。その新しいIssueをGood First Issueとしてマークするための条件を満たすことができるかどうか検討してください。それができたら、これらは良い情報源になります。

2 - 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はそれに加えて次のことも行います。

• 必要に応じて、/assign Prowコマンドを使用して、特定の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全体でチャットボットスタイルのコマンドを利用してGitHub actionsを扱えるようにします。たとえば、ラベルの追加と削除、issueのクローズ、approverの割り当てなどが行なえます。Prowコマンドは、GitHubのコメントに/<command-name>という形式で入力します。

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

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をクローズします。

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

あなたの裁量で、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は一般にオープン後に短期間でクローズされます。しかし、オープンされたものの非アクティブになるissueもあります。逆に、90日以上オープンのままにしておく必要があるissueもあります。

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

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

重複したissue

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

リンク切れに関するissue

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

ブログに関するissue

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

PRをクローズするときに送信するメッセージの一部として、記事の更新とメンテナンスへのリンクを含めて案内しても構いません。

関連する正当な理由がある場合には、例外を設けても問題ありません。

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

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

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

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を再びオープンしてください。

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

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を再びオープンしてください。

スカッシュを行う

approverとして、pull request(PR)をレビューするときに、次のような場合があります。

• コントリビューターにコミットをスカッシュするように伝えます。
• コントリビューターの代わりにコミットをスカッシュします。
• コントリビューターにまだスカッシュしないように伝えます。
• スカッシュができないようにします。

コントリビューターにスカッシュを行うように伝える: 新しいコントリビューターは、pull request(PR)でコミットをスカッシュする必要があることを知らない場合があります。このような場合は、スカッシュするように案内し、役立つ情報へのリンクを表示し、必要であればサポートを手配できることを伝えます。以下は役立つリンクの例です。

• ドキュメントコントリビューター向けのpull requestを作成しコミットをスカッシュする。
• 開発者向けのダイアグラムを含むGitHub Workflow。

コントリビューターの代わりにコミットをスカッシュする: コントリビューターがコミットのスカッシュに困っている場合やPRをマージするまでに時間的に制約がある場合は、代わりにスカッシュを行うことができます。

• kubernetes/websiteリポジトリはpull requestマージのためスカッシュを許可するように設定されています。 単純にSquash commitボタンを選択します。
• PRの中でコントリビューターがメンテナーによるPR管理を有効にしている場合、メンテナーはコミットをスカッシュし、その結果をフォークに反映させることができます。スカッシュする前に、最新の変更を保存してPRにプッシュするように伝えます。スカッシュ後は、スカッシュされたコミットをローカルクローンにプルするように伝えます。
• GitHubにコミットをスカッシュさせるには、TideやGitHubがスカッシュを行うラベルを使うか、PRをマージするときにSquash commitボタンをクリックします。

コントリビューターにスカッシュを避けるように伝える

• もし1つのコミットが不具合や望ましくない変更を含み、最後のコミットでそのエラーを元に戻している場合は、コミットをスカッシュしないでください。GitHubのPRの「Files changed」タブやNetlifyのプレビューでは問題がないように見えても、このPRをマージすると他の人に対してリベースやマージのコンフリクトを発生させる可能性があります。他のコントリビューターにリスクを与えないように適切に介入してください。

決してスカッシュしないようにする

• 翻訳を開始する場合や、新しいバージョンのドキュメントをリリースする場合など、ユーザーのフォークではないブランチをマージするときは、決してコミットをスカッシュしないでください。 これらのファイルについてはコミット履歴を保持する必要があるため、スカッシュしないことが重要です。