プルリクエストのレビュー

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

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

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

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

はじめる前に

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

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

レビューのプロセス

一般に、コンテンツや文体に対するプルリクエストは、英語でレビューを行います。

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

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セクションまでスクロールし、deploy/netlifyの行のDetailsリンクをクリックして、Netlifyのプレビュービルドで変更点をプレビューします。

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

   1. コメントしたい場合は行の横の+マークをクリックします。
   2. その行に関するコメントを書き、Add single comment(1つのコメントだけを残したい場合)またはStart a review(複数のコメントを行いたい場合)のいずれかをクリックします。
   3. コメントをすべて書いたら、ページ上部のReview changesをクリックします。ここでは、レビューの要約を追加できます(コントリビューターにポジティブなコメントも書きましょう！)。必要に応じて、PRを承認したり、コメントしたり、変更をリクエストします。新しいコントリビューターの場合はCommentだけが行えます。

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

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

言語と文法

• 言語や文法に明らかな間違いはないですか？ もっとよい言い方はないですか？
• もっと簡単な単語に置き換えられる複雑な単語や古い単語はありませんか？
• 使われている単語や専門用語や言い回しで差別的ではない別の言葉に置き換えられるものはありませんか？
• 言葉選びや大文字の使い方はstyle guideに従っていますか？
• もっと短くしたり単純な文に書き換えられる長い文はありませんか？
• 箇条書きやテーブルでもっとわかりやすく表現できる長いパラグラフはありませんか？

コンテンツ

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

ウェブサイト

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

その他

PRに関して誤字や空白などの小さな問題を指摘する場合は、コメントの前にnit:と書いてください。こうすることで、PRの作者は問題が深刻なものではないことが分かります。