このセクションでは、新しいコンテンツの貢献を行う前に知っておくべき情報を説明します。
flowchart LR
subgraph second[始める前に]
direction TB
S[ ] -.-
A[CNCF CLAに署名] --> B[Gitブランチを選択]
B --> C[言語ごとにPR]
C --> F[コントリビューターのための
ツールをチェックアウト] end subgraph first[貢献の基本] direction TB T[ ] -.- D[ドキュメントをMarkdownで書き
Hugoでサイトをビルド] --- E[GitHubにあるソース] E --- G[複数の言語のドキュメントを含む
'/content/../docs'フォルダー] G --- H[Hugoのpage content
typesやshortcodeをレビュー] 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,C,D,E,F,G,H grey class S,T spacewhite class first,second white
ツールをチェックアウト] end subgraph first[貢献の基本] direction TB T[ ] -.- D[ドキュメントをMarkdownで書き
Hugoでサイトをビルド] --- E[GitHubにあるソース] E --- G[複数の言語のドキュメントを含む
'/content/../docs'フォルダー] G --- H[Hugoのpage content
typesやshortcodeをレビュー] 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,C,D,E,F,G,H grey class S,T spacewhite class first,second white
図 - 新しいコンテンツ提供の貢献方法
上記の図は新しいコンテンツを申請する前に知っておくべき情報を示しています。 詳細については以下で説明します。
貢献の基本
- KubernetesのドキュメントはMarkdownで書き、KubernetesのウェブサイトはHugoを使ってビルドします。
- Kubernetesのドキュメントは、MarkdownのスタイルとしてCommonMarkを使用しています。
- ソースはGitHubにあります。Kubernetesのドキュメントは
/content/en/docs/
にあります。リファレンスドキュメントの一部は、update-imported-docs/
ディレクトリ内のスクリプトから自動的に生成されます。 - Page content typesにHugoによるドキュメントのコンテンツの見え方を記述しています。
- Kubernetesのドキュメントに貢献するのにDocsy shortcodeやカスタムのHugo shortcodeが使えます。
- 標準のHugoのshortcodeに加えて、多数のカスタムのHugo shortcodeを使用してコンテンツの見え方をコントロールしています。
- ドキュメントのソースは
/content/
内にある複数の言語で利用できます。各言語はそれぞれISO 639-1標準で定義された2文字のコードの名前のフォルダを持ちます。たとえば、英語のドキュメントのソースは/content/en/docs/
内に置かれています。 - 複数言語でのドキュメントへの貢献や新しい翻訳の開始に関する情報については、Kubernetesのドキュメントを翻訳するを参照してください。
始める前に
CNCF CLAに署名する
すべてのKubernetesのコントリビューターは、コントリビューターガイドを読み、Contributor License Agreement(コントリビューターライセンス契約、CLA)への署名を必ず行わなければなりません。
CLAへの署名が完了していないコントリビューターからのpull requestは、自動化されたテストで失敗します。名前とメールアドレスはgit config
コマンドで表示されるものに一致し、gitの名前とメールアドレスはCNCF CLAで使われたものに一致しなければなりません。
どのGitブランチを使用するかを選ぶ
pull requestをオープンするときは、どのブランチをベースにして作業するかをあらかじめ知っておく必要があります。
シナリオ | ブランチ |
---|---|
現在のリリースに対する既存または新しい英語のコンテンツ | main |
機能変更のリリースに対するコンテンツ | 機能変更が含まれるメジャーおよびマイナーバージョンに対応する、dev-<version> というパターンのブランチを使います。たとえば、機能変更がv1.33 に含まれる場合、ドキュメントの変更はdev-1.33 ブランチに追加します。 |
他の言語内のコンテンツ(翻訳) | 各翻訳対象の言語のルールに従います。詳しい情報は、翻訳のブランチ戦略を読んでください。 |
それでも選ぶべきブランチがわからないときは、Slack上の#sig-docs
チャンネルで質問してください。
備考:
すでにpull requestを作成していて、ベースブランチが間違っていたことに気づいた場合は、作成者であるあなただけがベースブランチを変更できます。言語ごとのPR
pull requestはPRごとに1つの言語に限定してください。複数の言語に同一の変更を行う必要がある場合は、言語ごとに別々のPRを作成してください。
コントリビューターのためのツール
kubernetes/website
リポジトリ内のdoc contributors toolsディレクトリには、コントリビューターとしての旅を楽にしてくれるツールがあります。