これは、このセクションの複数ページの印刷可能なビューです。 印刷するには、ここをクリックしてください.
Kubernetesに貢献する方法はたくさんあります。 新機能の設計に取り組むこともできますし、既存のコードにドキュメントを追加することも、ブログで記事を書くこともできます。 それだけではありません。新機能を実装したり、バグを修正したりすることもできます。 貢献者コミュニティへの参加を支援することも、既存の貢献者をサポートすることもできます。
様々な方法でプロジェクトに貢献することができるため、Kubernetesは https://k8s.dev/ という専用のウェブサイトを作成しました。 Kubernetesへの貢献についてもっと学ぶために、参照することができます。
もし この ドキュメントへの貢献について特に学びたい場合は、Kubernetesドキュメントへの貢献を参照してください。
このウェブサイトはKubernetes SIG Docsが管理しています。 Kubernetesプロジェクトは初心者でも経験者でも、全てのコントリビューターからの改善を歓迎しています！
Kubernetesドキュメントコントリビューターは
どなたでも、問題を説明するissueや、ドキュメントの改善を求めるissueを作成し、kubernetes/website GitHubリポジトリに対するプルリクエスト(PR)を用いて変更に貢献することができます。
Kubernetesコミュニティで効果的に働くためには、gitとGitHubを基本的に使いこなせる必要があります。
ドキュメンテーションに関わるには:
flowchart TB
subgraph third[プルリクエストのオープン]
direction TB
U[ ] -.-
Q[コンテンツを改善する] --- N[コンテンツを作成する]
N --- O[ドキュメントを翻訳する]
O --- P[k8sリリースサイクルの
ドキュメントを管理する]
end
subgraph second[レビュー]
direction TB
T[ ] -.-
D[kubernetes/website
リポジトリを確認する] --- E[静的サイトジェネレーター
Hugoを確認する]
E --- F[基本的なGitHubの
コマンドを理解する]
F --- G[オープンした
プルリクエストを確認し
レビュープロセスを見直す]
end
subgraph first[サインアップ]
direction TB
S[ ] -.-
B[CNCFの
コントリビューターライセンス
サインに署名する] --- C[Slackチャンネル
sig-docs に
参加する]
C --- V[kubernetes-sig-docsの
メーリングリストに
参加する]
V --- M[毎週開催している
sig-docs callsや
slack callsに
参加する]
end
A([fa:fa-user 新たな
コントリビューター]) --> first
A --> second
A --> third
A --> H[質問をする!!!]
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,M,Q,N,O,P,V grey
class S,T,U spacewhite
class first,second,third white
図1は新たなコントリビューターのためのロードマップを概説しています。サインアップやレビューのステップのいくつか、またはその全てに従えばよいです。これで、プルリクエストのオープンの下にリストされているいくつかの貢献目標を達成するためのプルリクエストを開く準備が整いました。また、質問はいつでも歓迎です！
一部のタスクでは、Kubernetes organizationで、より多くの信頼とアクセス権限が必要です。 役割と権限についての詳細は、SIG Docsへの参加を参照してください。
あらかじめいくつかのステップを見直すことで、最初の貢献に備えることができます。図2はそれらのステップの概説で、詳細は次のとおりです。
flowchart LR
subgraph second[はじめての貢献]
direction TB
S[ ] -.-
G[K8sメンバーからの
PRレビューを受ける] -->
A[最初のPRを作成するための
良いissueを
kubernetes/websiteから探す] --> B[PRをオープンする!!]
end
subgraph first[推奨される準備]
direction TB
T[ ] -.-
D[コントリビューターの概要を読む] -->E[K8sのコンテンツと
スタイルガイドを読む]
E --> F[Hugoのページコンテンツタイプと
ショートコードについて学ぶ]
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,D,E,F,G grey
class S,T spacewhite
class first,second white
kubernetes/website のissueリストを確認してください。はじめて貢献を行うのは大変なことかもしれません。新規コントリビューターのためのアンバサダーは、最初の数回の貢献を行う手助けをしてくれます。Kubernetes Slackで、特に#sig-docsチャンネルを用いて連絡を取ることができます。また毎月第一火曜日に行われる新規コントリビューターのための歓迎会もあります。ここで新規コントリビューターのアンバサダーと交流し、質問に答えてもらうことができます。
訳注: 日本語ローカライゼーションに関しては、Slackのkubernetes-docs-jaチャンネルを利用してください。
SIG DocsはKubernetesのドキュメントとウェブサイトを公開・管理するコントリビューターのグループです。SIG Docsに参加することはKubernetesコントリビューター(機能開発でもそれ以外でも)にとってKubernetesプロジェクトに大きな影響を与える素晴らしい方法の一つです。
SIG Docsは複数の方法でコミュニケーションをとっています。
#sig-docsに参加してください。自己紹介を忘れずに！kubernetes-docs-jaチャンネルを利用してください。kubernetes-sig-docsメーリングリストに参加してください。ここでは幅広い議論が起こり、公式な決定が記録されます。#sig-docsでアナウンスされ、Kubernetesコミュニティミーティングカレンダーに追加されます。Zoomクライアントをダウンロードするか、電話を使って通話する必要があります。Kubernetesのドキュメントに何か問題を見つけたり、新しいコンテンツに関してアイデアを思い付いたときは、issueを作ってください。必要なものは、GitHubアカウントとウェブブラウザーだけです。
Kubernetesのドキュメント上の新しい作業は、ほとんどの場合、GitHubのissueから始まります。Kubernetesのコントリビューターは、必要に応じてレビュー、分類、タグ付けを行います。次に、あなたやKubernetesコミュニティの他のメンバーが、そのissueを解決するための変更を加えるpull requestを開きます。
既存のコンテンツに対して改善を提案したい場合や、間違いを発見した場合は、issueを作ってください。
送信後、定期的にissueを確認するか、GitHubの通知を設定してください。レビュアや他のコミュニティメンバーが、issueに対して作業を行うために、あなたに何か質問をするかもしれません。
新しいコンテンツに関するアイデアがあるものの、どの場所に追加すればわからないときでも、issueを作ることができます。次のいずれかを選択して行ってください。
issueを作るときは、以下のことを心に留めてください。
#の文字を付けて参照する。例えば、Introduced by #987654のように書きます。このセクションでは、新しいコンテンツの貢献を行う前に知っておくべき情報を説明します。
図 - 新しいコンテンツ提供の貢献方法
上記の図は新しいコンテンツを申請する前に知っておくべき情報を示しています。 詳細については以下で説明します。
/content/en/docs/にあります。リファレンスドキュメントの一部は、update-imported-docs/ディレクトリ内のスクリプトから自動的に生成されます。/content/内にある複数の言語で利用できます。各言語はそれぞれISO 639-1標準で定義された2文字のコードの名前のフォルダを持ちます。たとえば、英語のドキュメントのソースは/content/en/docs/内に置かれています。すべてのKubernetesのコントリビューターは、コントリビューターガイドを読み、Contributor License Agreement(コントリビューターライセンス契約、CLA)への署名を必ず行わなければなりません。
CLAへの署名が完了していないコントリビューターからのpull requestは、自動化されたテストで失敗します。名前とメールアドレスはgit configコマンドで表示されるものに一致し、gitの名前とメールアドレスはCNCF CLAで使われたものに一致しなければなりません。
pull requestをオープンするときは、どのブランチをベースにして作業するかをあらかじめ知っておく必要があります。
| シナリオ | ブランチ |
|---|---|
| 現在のリリースに対する既存または新しい英語のコンテンツ | main |
| 機能変更のリリースに対するコンテンツ | 機能変更が含まれるメジャーおよびマイナーバージョンに対応する、dev-<version>というパターンのブランチを使います。たとえば、機能変更がv1.31に含まれる場合、ドキュメントの変更はdev-1.31ブランチに追加します。 |
| 他の言語内のコンテンツ(翻訳) | 各翻訳対象の言語のルールに従います。詳しい情報は、翻訳のブランチ戦略を読んでください。 |
それでも選ぶべきブランチがわからないときは、Slack上の#sig-docsチャンネルで質問してください。
pull requestはPRごとに1つの言語に限定してください。複数の言語に同一の変更を行う必要がある場合は、言語ごとに別々のPRを作成してください。
kubernetes/websiteリポジトリ内のdoc contributors toolsディレクトリには、コントリビューターとしての旅を楽にしてくれるツールがあります。
このセクションでは、コンテンツのレビュー方法について説明します。
ドキュメントのプルリクエストは誰でもレビューすることができます。Kubernetesのwebsiteリポジトリでpull requestsのセクションに移動し、open状態のプルリクエストを確認してください。
ドキュメントのプルリクエストのレビューは、Kubernetesコミュニティに自分を知ってもらうためのよい方法の1つです。コードベースについて学んだり、他のコントリビューターとの信頼関係を築く助けともなるはずです。
レビューを行う前には、以下のことを理解しておくとよいでしょう。
レビューを始める前に、以下のことを心に留めてください。
一般に、コンテンツや文体に対するプルリクエストは、英語でレビューを行います。図1は、レビュープロセスについて手順の概要を示しています。 各ステップの詳細は次のとおりです。
(訳注:SIG Docs jaでは、日本語でも対応しています。日本語の翻訳に対するレビューは、日本語でも構いません。ただし、プルリクエストの作成者や他のコントリビューターが必ずしも日本語を理解できるとは限りませんので、注意して発言してください。)
図1. レビュープロセスの手順
https://github.com/kubernetes/website/pullsに移動します。Kubernetesのウェブサイトとドキュメントに対するopen状態のプルリクエスト一覧が表示されます。
open状態のPRに、以下に示すラベルを1つ以上使って絞り込みます。
cncf-cla: yes (推奨): CLAにサインしていないコントリビューターが提出したPRはマージできません。詳しい情報は、CLAの署名を読んでください。language/en (推奨): 英語のPRだけに絞り込みます。size/<size>: 特定の大きさのPRだけに絞り込みます。レビューを始めたばかりの人は、小さなPRから始めてください。さらに、PRがwork in progressとしてマークされていないことも確認してください。work in progressラベルの付いたPRは、まだレビューの準備ができていない状態です。
レビューするPRを選んだら、以下のことを行い、変更点について理解します。
Files changedタブに移動してレビューを始めます。
コメントしたい場合は行の横の+マークをクリックします。
その行に関するコメントを書き、Add single comment(1つのコメントだけを残したい場合)またはStart a review(複数のコメントを行いたい場合)のいずれかをクリックします。
コメントをすべて書いたら、ページ上部のReview changesをクリックします。ここでは、レビューの要約を追加できます(コントリビューターにポジティブなコメントも書きましょう！)。常に「Comment」を使用してください。
レビューするときは、最初に以下の点を確認してみてください。
レビュアーが誤字や不適切な空白など、PRの本質でない小さな問題を発見した場合は、コメントの先頭にnit:を付けてください。これにより、作成者はこのフィードバックが重要でないことを知ることができます。
Pull Requestの承認を検討する際、残りのすべてのフィードバックがnitとしてマークされていれば、残っていたとしてもPRをマージできます。その場合、残っているnitに関するIssueをオープンすると役立つことがよくあります。その新しいIssueをGood First Issueとしてマークするための条件を満たすことができるかどうか検討してください。それができたら、これらは良い情報源になります。
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を割り当てます。
KubernetesのドキュメントはKubernetesコードレビュープロセスに従います。
pull requestのレビューに書かれているすべてのことが適用されますが、ReviewerとApproverはそれに加えて次のことも行います。
必要に応じて、/assignProwコマンドを使用して、特定のreviewerにPRを割り当てる。これは、コードのコントリビューターからの技術的なレビューが必要な場合には特に重要です。
reviewersフィールドを確認してください。PRがコンテンツおよびスタイルのガイドに従っていることを確認してください。ガイドに従っていない場合は、ガイドの関連する部分にリンクを作者に示してください。
PRの作者に変更を提案できるときは、GitHubのRequest Changes(変更をリクエスト)オプションを利用してください。
提案したことが反映されたら、/approveや/lgtmコマンドを使用して、GitHubのレビューステータスを変更してください。
PRにコメントを残すのは助けになりますが、まれに他の作者のPRに代わりにコミットを追加する必要がある場合があります。
あなたが明示的に作者から頼まれたり、長い間放置されたPRを蘇らせるような場合でない限り、他の作者のPRを「乗っ取る」ようなことはしないでください。短期的に見ればそのほうが短時間で終わるかもしれませんが、そのようなことをするとその人が貢献するチャンスを奪ってしまうことになります。
あなたが取る方法は、編集する必要のあるファイルがすでにPRのスコープに入っているか、あるいはPRがまだ触れていないファイルであるかによって変わります。
以下のいずれかが当てはまる場合、他の作者のPRにあなたがコミットを追加することはできません。
PRの作者が自分のブランチを直接https://github.com/kubernetes/website/リポジトリにpushした場合。この場合、pushアクセス権限を持つreviewerしか他のユーザーのPRにコミットを追加することはできません。
PRの作者が明示的にapproverからの編集を禁止している場合。
Prowは、pull request(PR)に対してジョブを実行するKubernetesベースのCI/CDシステムです。Prowは、Kubernetes organization全体でchatbotスタイルのコマンドを利用してGitHub actionsを扱えるようにします。たとえば、ラベルの追加と削除、issueのclose、approverの割り当てなどが行なえます。Prowコマンドは、GitHubのコメントに/<command-name>という形式で入力します。
reviewerとapproverが最もよく使うprowコマンドには、以下のようなものがあります。
| 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コマンドリファレンスを参照してください。
一般に、SIG DocsはKubernetes issue triageのプロセスに従い、同じラベルを使用しています。
このGitHub issueのフィルターは、トリアージが必要な可能性があるissueを表示します。
triage/needs-informationラベルを追加する。lifecycle/staleとtriage/needs-informationの両方のラベルがあるときは、issueをcloseする。| ラベル | 説明 |
|---|---|
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で質問してください。
ラベルを追加するには、以下のいずれかの形式でコメントします。
/<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は一般にopen後に短期間でcloseされます。しかし、issueがopenされた後にアクティブでなくなったり、issueが90日以上openのままである場合もあります。
| ラベル | 説明 |
|---|---|
lifecycle/stale | 90日間活動がない場合、issueは自動的にstaleとラベル付けされます。/remove-lifecycle staleコマンドを使って手動でlifecycleをリバートしない限り、issueは自動的にcloseされます。 |
lifecycle/frozen | このラベルが付けられたissueは、90日間活動がなくてもstaleになりません。priority/important-longtermラベルを付けたissueなど、90日以上openにしておく必要があるissueには、このラベルを手動で追加します。 |
SIG Docsでは、対処方法をドキュメントに書いても良いくらい頻繁に、以下のような種類のissueに出会います。
1つの問題に対して1つ以上のissueがopenしている場合、1つのissueに統合します。あなたはどちらのissueをopenにしておくか(あるいは新しいissueを作成するか)を決断して、すべての関連する情報を移動し、関連するすべてのissueにリンクしなければなりません。最後に、同じ問題について書かれたすべての他のissueにtriage/duplicateラベルを付けて、それらをcloseします。作業対象のissueを1つだけにすることで、混乱を減らし、同じ問題に対して作業が重複することを避けられます。
リンク切れのissueがAPIまたはkubectlのドキュメントにあるものは、問題が完全に理解されるまでは/priority critical-urgentを割り当ててください。その他のすべてのリンク切れに関するissueには、手動で修正が必要であるため、/priority important-longtermを付けます。
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してください。
このページでは、Kubernetesドキュメントにおける日本語翻訳の方針について説明します。
翻訳を行うための基本的な流れについて説明します。不明点がある場合はKubernetes公式Slackの#kubernetes-docs-jaチャンネルにてお気軽にご質問ください。
翻訳作業は全てGitHubのIssueによって管理されています。翻訳作業を行いたい場合は、Issueの一覧をまず最初にご確認ください。
また、Kubernetes傘下のリポジトリではCLAと呼ばれる同意書に署名しないと、Pull Requestをマージすることができません。詳しくは英語のドキュメントや、Qiitaに有志の方が書いてくださった日本語のまとめをご覧ください。
/assignと書く不明点がある場合はKubernetes公式Slackの#kubernetes-docs-jaチャンネルにてお気軽にご質問ください。
/assignと書くkubernetes/websiteリポジトリをフォークするmainから任意の名前でブランチを作成するcontent/enのディレクトリから必要なファイルをcontent/jaにコピーし、翻訳するmainブランチに向けてPull Requestを作成するkubernetes/websiteリポジトリをフォークするmainから任意の名前でブランチを作成するcontent/jaのディレクトリから必要なファイルを編集するmainブランチに向けてPull Requestを作成するreviewerの項目は削除する/ja/を含めたURLを使用する/path/to/page/ではなく、/ja/path/to/page/を使用するKubernetesのリソース名や技術用語などは、原則としてそのままの表記を使用します。 例えば、PodやService、Deploymentなどは翻訳せずにそのまま表記してください。
ただし、ノード(Node)に関しては明確にKubernetesとしてのNodeリソース(例: kind: Nodeやkubectl get nodes)を指していないのであれば、「ノード」と表記してください。
またこれらの単語は、複数形ではなく単数形を用います。 例えば、原文に"pods"と表記されている場合でも、日本語訳では"Pod"と表記してください。
| よくある表記 | あるべき形 |
|---|---|
| 〜ので、〜から、〜だから | 〜のため 、〜ため |
| (あいうえお。) | (あいうえお)。 |
| 〇,〇,〇 | 〇、〇、〇(※列挙はすべて読点で統一) |
カタカナ語に長音を付与するかどうかは、以下の原則に従ってください。
ただし、「コンテナ」は例外的に長音を付与しないこととします。
この原則を作成するにあたって、mozilla-japan/translation Editorial Guideline#カタカナ語の表記を参考にしました。
その他の表記については、以下の表を参考にしてください。
| 英語 | 日本語 |
|---|---|
| interface | インターフェース |
| proxy | プロキシ |
| quota | クォータ |
| stacked | 積層 |
混同を避けるため、cron jobはcronジョブと訳し、CronJobはリソース名としてそのまま表記します。 cron「の」ジョブは、「の」が続く事による解釈の難から基本的にはつけないものとします。
#kubernetes-docs-jaで相談する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を含む各SIGは、議長として機能する1人以上のSIGメンバーを選択します。 これらは、SIGDocsとKubernetes organizationの他の部分との連絡先です。 それらには、Kubernetesプロジェクト全体の構造と、SIG Docsがその中でどのように機能するかについての広範な知識が必要です。 現在のchairpersonのリストについては、 Leadership を参照してください。
SIG Docsの自動化は、GitHub teamsとOWNERSファイルの2つの異なるメカニズムに依存しています。
GitHubには、二つのSIG Docs teams カテゴリがあります:
@sig-docs-{language}-ownersは承認者かつリードです。@sig-docs-{language}-reviews はレビュアーです。それぞれをGitHubコメントの@nameで参照して、そのグループの全員とコミュニケーションできます。
ProwチームとGitHub teamsが完全に一致せずに重複する場合があります。 問題の割り当て、Pull Request、およびPR承認のサポートのために、自動化ではOWNERSファイルからの情報を使用します。
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がコンテンツの公開に使用されるブランチにマージされると、そのコンテンツは http://kubernetes.io に公開されます。 公開されたコンテンツの品質を高くするために、Pull RequestのマージはSIG Docsの承認者に限定しています。仕組みは次のとおりです。
lgtmラベルとapproveラベルの両方があり、holdラベルがなく、すべてのテストに合格すると、Pull Requestは自動的にマージされます。/holdコメントを追加するか、/lgtmコメントを保留します)。/lgtmコメントを追加することでlgtmラベルを追加できます。/approveコメントを追加してPull Requestをマージできるのは、SIG Docsの承認者だけです。一部の承認者は、PR WranglerやSIG Docsのchairpersonなど、追加の特定の役割も実行します。Kubernetesドキュメントへの貢献の詳細については、以下を参照してください：
このセクション内のトピックでは、文章のスタイル、コンテンツの形式や構成、特にKubernetesのドキュメント特有のHugoカスタマイズの使用方法に関するガイダンスを提供します。
このページでは、Kubernetesのドキュメント上のコンテンツのガイドラインを説明します。
許可されるコンテンツに関して疑問がある場合は、Kubernetes Slackの#sig-docsチャンネルに参加して質問してください！
Kubernetes Slackには、https://slack.k8s.io/ から参加登録ができます。
Kubernetesドキュメントの新しいコンテンツの作成に関する情報については、スタイルガイドに従ってください。
ドキュメントを含むKubernetesのウェブサイトのソースは、kubernetes/websiteリポジトリに置かれています。
Kubernetesの主要なドキュメントはkubernetes/website/content/<language_code>/docsフォルダに置かれており、これらはKubernetesプロジェクトを対象としています。
Kubernetesのドキュメントにサードパーティーのコンテンツを掲載することが許されるのは、次の場合のみです。
Kubernetesのドキュメントには、Kubernetesプロジェクト(kubernetesおよびkubernetes-sigs GitHub organizationsに存在するプロジェクト)の適用例が含まれています。
Kubernetesプロジェクト内のアクティブなコンテンツへのリンクは常に許可されます。
Kubernetesを機能させるためには、一部サードパーティーのコンテンツが必要です。たとえば、コンテナランタイム(containerd、CRI-O、Docker)、ネットワークポリシー(CNI plugin)、Ingressコントローラー、ロギングなどです。
ドキュメント内で、Kubernetesプロジェクト外のサードパーティーのオープンソースソフトウェア(OSS)にリンクすることができるのは、Kubernetesを機能させるために必要な場合のみです。
可能な限り、Kubernetesのドキュメントは正規の情報源にリンクするようにし、情報源が重複してしまうようなホスティングは行いません。
情報源が重複したコンテンツは、メンテナンスするために2倍の労力(あるいはそれ以上！)が必要になり、より早く情報が古くなってしまいます。
許可されるコンテンツに関して疑問がある場合は、Kubernetes Slackの#sig-docsチャンネルに参加して質問してください！
このサイトではHugoを使用しています。Hugoでは、コンテンツの構造化がコアコンセプトとなっています。
hugo server --navigateToChangedコマンドを使用してHugoを実行してください。ドキュメントのサイドメニューやページブラウザーなどでは、Hugoのデフォルトのソート順序を使用して一覧を作成しています。デフォルトでは、weight(1から開始)、日付(最新のものが1番目)、最後にリンクのタイトルの順でソートされます。
そのため、特定のページやセッションを上に移動したい場合には、ページのフロントマター内のweightを設定します。
title: My Page
weight: 10
ドキュメントのメインメニューは、docs/以下に置かれたセクションのコンテンツファイル_index.mdのフロントマター内にmain_menuフラグが設定されたものから生成されます。
main_menu: true
リンクのタイトルは、ページのlinkTitleから取得されることに注意してください。そのため、ページのタイトルとは異なるリンクテキストにしたい場合、コンテンツファイル内の値を以下のように設定します。
main_menu: true
title: ページタイトル
linkTitle: リンク内で使われるタイトル
_index.mdコンテンツファイルを作成してください。ドキュメントのサイドバーメニューは、docs/以下の現在のセクションツリーから生成されます。
セクションと、そのセクション内のページがすべて表示されます。
特定のセクションやページをリストに表示したくない場合、フロントマター内のtoc_hideフラグをtrueに設定してください。
toc_hide: true
コンテンツが存在するセクションに移動すると、特定のセクションまたはページ(例:index.md)が表示されます。それ以外の場合、そのセクションの最初のページが表示されます。
ドキュメントのホームページのページブラウザーは、docsセクション直下のすべてのセクションとページを使用して生成されています。
特定のセクションやページを表示したくない場合、フロントマターのtoc_hideフラグをtrueに設定してください。
toc_hide: true
右上のメニュー(およびフッター)にあるサイトリンクは、page-lookupの機能を使用して実装されています。これにより、ページが実際に存在することを保証しています。そのため、たとえばcase-studiesのセクションが特定の言語のサイトに存在しない場合、メニューにはケーススタディのリンクが表示されません。
スタンドアローンのコンテンツページ(Markdownファイル)に加えて、Hugoでは、Page Bundlesがサポートされています。
Page Bundleの1つの例は、カスタムのHugo Shortcodeです。これは、leaf bundleであると見做されます。ディレクトリ内のすべてのファイルは、index.mdを含めてバンドルの一部となります。これには、ページからの相対リンク、処理可能な画像なども含まれます。
en/docs/home/contribute/includes
├── example1.md
├── example2.md
├── index.md
└── podtemplate.json
もう1つのPage Bundleがよく使われる例は、includesバンドルです。フロントマターにheadless: trueを設定すると、自分自身のURLを持たなくなり、他のページ内でのみ使用されるようになります。
en/includes
├── default-storage-class-prereqs.md
├── index.md
├── partner-script.js
├── partner-style.css
├── task-tutorial-prereqs.md
├── user-guide-content-moved.md
└── user-guide-migration-notice.md
バンドル内のファイルに関して、いくつか重要な注意点があります。
Resourcesと呼ぶファイルになり、フロントマター(YAMLファイルなど)をサポートしていない場合であっても、言語ごとにパラメーターやタイトルなどのメタデータを提供できます。詳しくは、Page Resourcesメタデータを参照してください。Resourceの.RelPermalinkから取得した値は、ページからの相対的なものとなっています。詳しくは、Permalinksを参照してください。このサイトのスタイルシートのSASSのソースは、assets/sassに置かれていて、Hugoによって自動的にビルドされます。
このページではKubernetesのマークダウンドキュメント内で使用できるHugoショートコードについて説明します。
ショートコードについての詳細はHugoのドキュメントを読んでください。
このサイトのマークダウンページ(.mdファイル)内では、説明されている機能のバージョンや状態を表示するためにショートコードを使用することができます。
最新のKubernetesバージョンで機能をstableとして表示するためのデモスニペットを次に示します。
{{< feature-state state="stable" >}}
これは次の様に表示されます:
Kubernetes v1.30 [stable]stateの値として妥当な値は次のいずれかです:
表示されるKubernetesのバージョンのデフォルトはそのページのデフォルトまたはサイトのデフォルトです。
for_k8s_versionパラメーターを渡すことにより、機能の状態バージョンを変更することができます。
例えば:
{{< feature-state for_k8s_version="v1.10" state="beta" >}}
これは次の様に表示されます:
Kubernetes v1.10 [beta]用語集に関連するショートコードとして、glossary_tooltipとglossary_definitionの二つがあります。
コンテンツを自動的に更新し、用語集へのリンクを付与する挿入を使用して、用語を参照することができます。 用語がマウスオーバーされると、用語集の内容がツールチップとして表示されます。 また、用語はリンクとして表示されます。
ツールチップの挿入と同様に、用語集の定義も再利用することができます。
用語集の用語データはglossaryディレクトリに、それぞれの用語のファイルとして保存されています。
例えば、マークダウン内でツールチップ付きのclusterを表示するには、次の挿入を使用します:
{{< glossary_tooltip text="cluster" term_id="cluster" >}}
用語集の定義はこのようにします:
{{< glossary_definition prepend="A cluster is" term_id="cluster" length="short" >}}
これは次の様に表示されます:
A cluster is コンテナ化されたアプリケーションを実行する、ノードと呼ばれるワーカーマシンの集合です。すべてのクラスターには少なくとも1つのワーカーノードがあります。
完全な用語定義を挿入することもできます:
{{< glossary_definition term_id="cluster" length="all" >}}
これは次の様に表示されます:
コンテナ化されたアプリケーションを実行する、ノードと呼ばれるワーカーマシンの集合です。すべてのクラスターには少なくとも1つのワーカーノードがあります。
ワーカーノードは、アプリケーションのコンポーネントであるPodをホストします。マスターノードは、クラスター内のワーカーノードとPodを管理します。複数のマスターノードを使用して、クラスターにフェイルオーバーと高可用性を提供します。 ワーカーノードは、アプリケーションワークロードのコンポーネントであるPodをホストします。コントロールプレーンは、クラスター内のワーカーノードとPodを管理します。本番環境では、コントロールプレーンは複数のコンピューターを使用し、クラスターは複数のノードを使用し、耐障害性や高可用性を提供します。
api-referenceショートコードを使用することで、Kubernetes APIリファレンスへのリンクを作成することができます。
例えば、
Podへの参照方法は次の通りです:
{{< api-reference page="workload-resources/pod-v1" >}}
pageパラメーターの値はAPIリファレンスページのURLの末尾です。
anchorパラメーターを指定することでページ内の特定の場所へリンクすることもできます。
例えば、
PodSpecや
environment-variablesへのリンクは次の様に書きます:
{{< api-reference page="workload-resources/pod-v1" anchor="PodSpec" >}}
{{< api-reference page="workload-resources/pod-v1" anchor="environment-variables" >}}
textパラメーターを指定することでリンクテキストを変更することもできます。
例えば、
Environment Variablesへのリンクは次の様に書きます:
{{< api-reference page="workload-resources/pod-v1" anchor="environment-variables" text="Environment Variable" >}}
テーブルキャプションを追加することで、表をスクリーンリーダーにとってよりアクセスしやすいものにする事ができます。
表へキャプションを追加するには、表をtableショートコードで囲い、captionパラメーターにキャプションを指定します。
例えば、次の様に書きます:
{{< table caption="Configuration parameters" >}}
Parameter | Description | Default
:---------|:------------|:-------
`timeout` | The timeout for requests | `30s`
`logLevel` | The log level for log output | `INFO`
{{< /table >}}
これは次の様に表示されます:
| Parameter | Description | Default |
|---|---|---|
timeout | The timeout for requests | 30s |
logLevel | The log level for log output | INFO |
この表に対するHTMLを検査すると、次の要素が<table>要素のすぐ次にあるのを見ることができるでしょう:
<caption style="display: none;">Configuration parameters</caption>
このサイトのマークダウンページ(.mdファイル)内では、あるソリューションに対する複数のフレーバーを表示するためのタブセットを追加することができます。
tabsショートコードはこれらのパラメーターを受けとります:
name: タブに表示される名前codelang: 内側のtabショートコードにこれを指定した場合、Hugoはハイライトに使用するコード言語を知ることができます。include: タブ内で挿入するファイル。Hugo leaf bundle内にタブがある場合そのファイル(HugoがサポートしているどのMIMEタイプでも良い)はそのbundle自身によって探されます。
もしそうでない場合、そのコンテントページは現在のページから相対的に探されます。
includeを使う場合、ショートコードの内部コンテンツはなく、自己終了構文を使用する必要があることに注意してください。
例えば、{{< tab name="Content File #1" include="example1" />}}の様にします。
codelangを指定するか、ファイル名から言語が特定される必要があります。
非コンテンツファイルはデフォルトでコードが強調表示されます。%デリミターを使用する必要があります。
例えば、{{% tab name="Tab 1" %}}This is **markdown**{{% /tab %}}の様にします。タブショートコードの例を次に示します。
tabs定義内のnameはコンテンツページ内でユニークである必要があります。{{< tabs name="tab_with_code" >}}
{{{< tab name="Tab 1" codelang="bash" >}}
echo "これはタブ1です。"
{{< /tab >}}
{{< tab name="Tab 2" codelang="go" >}}
println "これはタブ2です。"
{{< /tab >}}}
{{< /tabs >}}
これは次の様に表示されます:
echo "これはタブ1です。"
println "これはタブ2です。"
{{< tabs name="tab_with_md" >}}
{{% tab name="Markdown" %}}
これは**なにがしかのマークダウン**です。
{{< note >}}
ショートコードを含むこともできます。
{{< /note >}}
{{% /tab %}}
{{< tab name="HTML" >}}
<div>
<h3>プレーンHTML</h3>
<p>これはなにがしかの<i>プレーン</i>HTMLです。</p>
</div>
{{< /tab >}}
{{< /tabs >}}
これは次の様に表示されます。
これはなにがしかのマークダウンです。
これはなにがしかのプレーンHTMLです。
{{< tabs name="tab_with_file_include" >}}
{{< tab name="Content File #1" include="example1" />}}
{{< tab name="Content File #2" include="example2" />}}
{{< tab name="JSON File" include="podtemplate" />}}
{{< /tabs >}}
これは次の様に表示されます:
これは挿入leaf bundle内のコンテンツファイルの例です。
これは挿入leaf bundle内のコンテンツファイルのもう一つの例です
{
"apiVersion": "v1",
"kind": "PodTemplate",
"metadata": {
"name": "nginx"
},
"template": {
"metadata": {
"labels": {
"name": "nginx"
},
"generateName": "nginx-"
},
"spec": {
"containers": [{
"name": "nginx",
"image": "dockerfile/nginx",
"ports": [{"containerPort": 80}]
}]
}
}
}
Kubernetesの実行にはサードパーティーのソフトウェアが必要です。 例えば、名前解決を行うためにはクラスターにDNSサーバーを追加する必要があります。
私たちがサードパーティーソフトウェアにリンクするときや言及するときは、コンテンツガイドに従い、サードパーティーのものに印をつけます。
これらのショートコードを使用すると、それらを使用しているドキュメントページに免責事項が追加されます。
サードパーティーのリストには、
{{% thirdparty-content %}}
をすべてのアイテムを含むセクションのヘッダーのすぐ下に追加します。
ほとんどのアイテムがプロジェクト内ソフトウェア(例えばKubernetes自体やDeschedulerコンポーネント)を参照している場合、違う形を使用することができます。
次のショートコードをアイテムの前か、特定のアイテムのヘッダーのすぐ下に追加します:
{{% thirdparty-content single="true" %}}
ドキュメント内でバージョン文字列を生成して挿入するために、いくつかのバージョンショートコードから選んで使用することができます。
それぞれのバージョンショートコードはサイトの設定ファイル(hugo.toml)から取得したバージョンパラメーターの値を使用してバージョン文字列を表示します。
最もよく使われる二つのバージョンパラメーターはlatestとversionです。
{{< param "version" >}}{{< param "version" >}}ショートコードはサイトのversionパラメーターに設定されたKubernetesドキュメントの現在のバージョンを生成します。
paramショートコードはサイトパラメーターの名前の一つを受けとり、この場合はversionを渡しています。
latestとversionの値は同じではありません。
新しいバージョンがリリースされると、latestはインクリメントされ、versionは変更されません。
例えば、以前にリリースされたドキュメントはversionをv1.19として表示し、latestをv1.20として表示します。これは次の様に表示されます:
v1.30{{< latest-version >}}{{< latest-version >}}ショートコードはサイトのlatestパラメーターの値を返します。
サイトのlatestパラメーターは新しいドキュメントのバージョンがリリースされた時に更新されます。
このパラメーターは必ずしもversionの値と一致しません。
これは次の様に表示されます:
v1.30{{< latest-semver >}}{{< latest-semver >}}ショートコードはlatestから"v"接頭辞を取り除いた値を生成します。
これは次の様に表示されます。
1.30{{< version-check >}}{{< version-check >}}ショートコードはページにmin-kubernetes-server-versionパラメーターがあるかどうか確認し、versionと比較するために使用します。
これは次の様に表示されます:
バージョンを確認するには次のコマンドを実行してください:kubectl version.{{< latest-release-notes >}}{{< latest-release-notes >}}ショートコードはlatestからバージョン文字列を生成し、"v"接頭辞を取り除きます。
このショートコードはバージョン文字列に対応したリリースノートCHANGELOGページのURLを表示します。
これは次の様に表示されます:
https://git.k8s.io/kubernetes/CHANGELOG/CHANGELOG-1.30.md