whentimeslows/website
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge branch 'master' into dev-1.19-ja.1

Browse Source
This commit is contained in:
inductor(Kohei)
2021-05-26 13:43:10 +09:00
committed by GitHub
parent 38977dfa71 d763553fc3
commit 496bccbe4f
1303 changed files with 115188 additions and 32099 deletions
Download Patch File Download Diff File Expand all files Collapse all files
content/ja/docs/contribute/new-content/_index.md
+4
View File
@@ -0,0 +1,4 @@
---
title: 新しいコンテンツの貢献
weight: 20
---
content/ja/docs/contribute/new-content/overview.md
+54
View File
@@ -0,0 +1,54 @@
---
title: 新しいコンテンツの貢献の概要
linktitle: 概要
content_type: concept
main_menu: true
weight: 5
---
<!-- overview -->
このセクションでは、新しいコンテンツの貢献を行う前に知っておくべき情報を説明します。
<!-- body -->
## 貢献の基本
- KubernetesのドキュメントはMarkdownで書き、Kubernetesのウェブサイトは[Hugo](https://gohugo.io/)を使ってビルドします。
- ソースは[GitHub](https://github.com/kubernetes/website)にあります。Kubernetesのドキュメントは`/content/en/docs/`にあります。リファレンスドキュメントの一部は、`update-imported-docs/`ディレクトリ内のスクリプトから自動的に生成されます。
- [Page content types](/docs/contribute/style/page-content-types/)にHugoによるドキュメントのコンテンツの見え方を記述しています。
- 標準のHugoのshortcodeに加えて、多数の[カスタムのHugo shortcode](/docs/contribute/style/hugo-shortcodes/)を使用してコンテンツの見え方をコントロールしています。
- ドキュメントのソースは`/content/`内にある複数の言語で利用できます。各言語はそれぞれ[ISO 639-1標準](https://www.loc.gov/standards/iso639-2/php/code_list.php)で定義された2文字のコードの名前のフォルダを持ちます。たとえば、英語のドキュメントのソースは`/content/en/docs/`内に置かれています。
- 複数言語でのドキュメントへの貢献や新しい翻訳の開始に関する情報については、[Kubernetesのドキュメントを翻訳する](/docs/contribute/localization)を参照してください。
## 始める前に {#before-you-begin}
### CNCF CLAに署名する {#sign-the-cla}
すべてのKubernetesのコントリビューターは、[コントリビューターガイド](https://github.com/kubernetes/community/blob/master/contributors/guide/README.md)を読み、[Contributor License Agreement(コントリビューターライセンス契約、CLA)への署名](https://github.com/kubernetes/community/blob/master/CLA.md)を**必ず行わなければなりません**。
CLAへの署名が完了していないコントリビューターからのpull requestは、自動化されたテストで失敗します。名前とメールアドレスは`git config`コマンドで表示されるものに一致し、gitの名前とメールアドレスはCNCF CLAで使われたものに一致しなければなりません。
### どのGitブランチを使用するかを選ぶ
pull requestをオープンするときは、どのブランチをベースにして作業するかをあらかじめ知っておく必要があります。
シナリオ | ブランチ
:---------|:------------
現在のリリースに対する既存または新しい英語のコンテンツ | `master`
機能変更のリリースに対するコンテンツ | 機能変更が含まれるメジャーおよびマイナーバージョンに対応する、`dev-<version>`というパターンのブランチを使います。たとえば、機能変更が`v{{< skew nextMinorVersion >}}`に含まれる場合、ドキュメントの変更は``dev-{{< skew nextMinorVersion >}}``ブランチに追加します。
他の言語内のコンテンツ(翻訳) | 各翻訳対象の言語のルールに従います。詳しい情報は、[翻訳のブランチ戦略](/docs/contribute/localization/#branching-strategy)を読んでください。
それでも選ぶべきブランチがわからないときは、Slack上の`#sig-docs`チャンネルで質問してください。
{{< note >}}
すでにpull requestを作成していて、ベースブランチが間違っていたことに気づいた場合は、作成者であるあなただけがベースブランチを変更できます。
{{< /note >}}
### 言語ごとのPR
pull requestはPRごとに1つの言語に限定してください。複数の言語に同一の変更を行う必要がある場合は、言語ごとに別々のPRを作成してください。
## コントリビューターのためのツール
`kubernetes/website`リポジトリ内の[doc contributors tools](https://github.com/kubernetes/website/tree/master/content/en/docs/doc-contributor-tools)ディレクトリには、コントリビューターとしての旅を楽にしてくれるツールがあります。
content/ja/docs/contribute/participate/_index.md
+102
View File
@@ -0,0 +1,102 @@
---
title: SIG Docsへの参加
content_type: concept
weight: 60
card:
name: contribute
weight: 60
---
<!-- overview -->
SIG Docsは、Kubernetesプロジェクト内の
[special interest groups](https://github.com/kubernetes/community/blob/master/sig-list.md)の1つであり、
Kubernetes全体のドキュメントの作成、更新、および保守に重点を置いています。
SIGの詳細については、[SIG DocsのGithubリポジトリ](https://github.com/kubernetes/community/blob/master/sig-list.md)を参照してください。
SIG Docsは、すべての寄稿者からのコンテンツとレビューを歓迎します。
誰でもPull Request(PR)を開くことができ、コンテンツに関するissueを提出したり、進行中のPull Requestにコメントしたりできます。
あなたは、[member](/docs/contribute/participate/roles-and-responsibilities/#members)や、
[reviewer](/docs/contribute/participate/roles-and-responsibilities/#reviewers)、
[approver](/docs/contribute/participate/roles-and-responsibilities/#approvers)になることもできます。
これらの役割にはより多くのアクセスが必要であり、変更を承認およびコミットするための特定の責任が伴います。
Kubernetesコミュニティ内でメンバーシップがどのように機能するかについての詳細は、
[community-membership](https://github.com/kubernetes/community/blob/master/community-membership.md)
をご覧ください。
このドキュメントの残りの部分では、kubernetesの中で最も広く公開されている
Kubernetesのウェブサイトとドキュメントの管理を担当しているSIG Docsの中で、これらの役割がどのように機能するのかを概説します。
<!-- body -->
## SIG Docs chairperson
SIG Docsを含む各SIGは、議長として機能する1人以上のSIGメンバーを選択します。
これらは、SIGDocsとKubernetes organizationの他の部分との連絡先です。
それらには、Kubernetesプロジェクト全体の構造と、SIG Docsがその中でどのように機能するかについての広範な知識が必要です。
現在のchairpersonのリストについては、
[Leadership](https://github.com/kubernetes/community/tree/master/sig-docs#leadership)
を参照してください。
## SIG Docs teamsと自動化
SIG Docsの自動化は、GitHub teamsとOWNERSファイルの2つの異なるメカニズムに依存しています。
### GitHub teams
GitHubには、二つのSIG Docs
[teams](https://github.com/orgs/kubernetes/teams?query=sig-docs)
カテゴリがあります:
- `@sig-docs-{language}-owners`は承認者かつリードです。
- `@sig-docs-{language}-reviewers` はレビュアーです。
それぞれをGitHubコメントの`@name`で参照して、そのグループの全員とコミュニケーションできます。
ProwチームとGitHub teamsが完全に一致せずに重複する場合があります。
問題の割り当て、Pull Request、およびPR承認のサポートのために、自動化ではOWNERSファイルからの情報を使用します。
### OWNERSファイルとfront-matter
Kubernetesプロジェクトは、GitHubのissueとPull Requestに関連する自動化のためにprowと呼ばれる自動化ツールを使用します。
[Kubernetes Webサイトリポジトリ](https://github.com/kubernetes/website)
は、2つの[prowプラグイン](https://github.com/kubernetes/test-infra/tree/master/prow/plugins)を使用します：
- blunderbuss
- approve
これらの2つのプラグインは`kubernetes.website`のGithubリポジトリのトップレベルにある
[OWNERS](https://github.com/kubernetes/website/blob/master/OWNERS)ファイルと、
[OWNERS_ALIASES](https://github.com/kubernetes/website/blob/master/OWNERS_ALIASES)ファイルを使用して、
リポジトリ内でのprowの動作を制御します。
OWNERSファイルには、SIG Docsのレビュー担当者および承認者であるユーザーのリストが含まれています。
OWNERSファイルはサブディレクトリに存在することもでき、そのサブディレクトリとその子孫のファイルのレビュー担当者または承認者として機能できるユーザーを上書きできます。
一般的なOWNERSファイルの詳細については、
[OWNERS](https://github.com/kubernetes/community/blob/master/contributors/guide/owners.md)を参照してください。
さらに、個々のMarkdownファイルは、個々のGitHubユーザー名またはGitHubグループを一覧表示することにより、そのfront-matterでレビュー担当者と承認者を一覧表示できます。
OWNERSファイルとMarkdownファイルのfront-matterの組み合わせにより、PRの技術的および編集上のレビューを誰に依頼するかについてPRの所有者が自動化システムから得るアドバイスが決まります。
## マージの仕組み
Pull Requestがコンテンツの公開に使用されるブランチにマージされると、そのコンテンツは http://kubernetes.io に公開されます。
公開されたコンテンツの品質を高くするために、Pull RequestのマージはSIG Docsの承認者に限定しています。仕組みは次のとおりです。
- Pull Requestに`lgtm`ラベルと`approve`ラベルの両方があり、`hold`ラベルがなく、すべてのテストに合格すると、Pull Requestは自動的にマージされます。
- Kubernetes organizationのメンバーとSIG Docsの承認者はコメントを追加して、特定のPull Requestが自動的にマージされないようにすることができます(`/hold`コメントを追加するか、`/lgtm`コメントを保留します)。
- Kubernetesメンバーは誰でも、`/lgtm`コメントを追加することで`lgtm`ラベルを追加できます。
- `/approve`コメントを追加してPull Requestをマージできるのは、SIG Docsの承認者だけです。一部の承認者は、[PR Wrangler](/docs/contribute/participate/pr-wranglers/)や[SIG Docsのchairperson](#sig-docs-chairperson)など、追加の特定の役割も実行します。
## {{% heading "whatsnext" %}}
Kubernetesドキュメントへの貢献の詳細については、以下を参照してください：
- [Contributing new content](/docs/contribute/new-content/overview/)
- [Reviewing content](/docs/contribute/review/reviewing-prs)
- [ドキュメントスタイルの概要](/ja/docs/contribute/style/)
content/ja/docs/contribute/review/reviewing-prs.md
+86
View File
@@ -0,0 +1,86 @@
---
title: プルリクエストのレビュー
content_type: concept
main_menu: true
weight: 10
---
<!-- overview -->
ドキュメントのプルリクエストは誰でもレビューすることができます。Kubernetesのwebsiteリポジトリで[pull requests](https://github.com/kubernetes/website/pulls)のセクションに移動し、open状態のプルリクエストを確認してください。
ドキュメントのプルリクエストのレビューは、Kubernetesコミュニティに自分を知ってもらうためのよい方法の1つです。コードベースについて学んだり、他のコントリビューターとの信頼関係を築く助けともなるはずです。
レビューを行う前には、以下のことを理解しておくとよいでしょう。
- [コンテンツガイド](/docs/contribute/style/content-guide/)と[スタイルガイド](/docs/contribute/style/style-guide/)を読んで、有益なコメントを残せるようにする。
- Kubernetesのドキュメントコミュニティにおける[役割と責任](/docs/contribute/participate/roles-and-responsibilities/)の違いを理解する。
<!-- body -->
## はじめる前に
レビューを始める前に、以下のことを心に留めてください。
- [CNCFの行動規範](https://github.com/cncf/foundation/blob/master/code-of-conduct.md)を読み、いかなる時にも行動規範にしたがって行動するようにする。
- 礼儀正しく、思いやりを持ち、助け合う気持ちを持つ。
- 変更点だけでなく、PRのポジティブな側面についてもコメントする。
- 相手の気持ちに共感して、自分のレビューが相手にどのように受け取られるのかをよく意識する。
- 相手の善意を前提として、疑問点を明確にする質問をする。
- 経験を積んだコントリビューターの場合、コンテンツに大幅な変更が必要な新規のコントリビューターとペアを組んで作業に取り組むことを考える。
## レビューのプロセス
一般に、コンテンツや文体に対するプルリクエストは、英語でレビューを行います。
1. [https://github.com/kubernetes/website/pulls](https://github.com/kubernetes/website/pulls)に移動します。Kubernetesのウェブサイトとドキュメントに対するopen状態のプルリクエスト一覧が表示されます。
2. open状態のPRに、以下に示すラベルを1つ以上使って絞り込みます。
- `cncf-cla: yes` (推奨): CLAにサインしていないコントリビューターが提出したPRはマージできません。詳しい情報は、[CLAの署名](/docs/contribute/new-content/overview/#sign-the-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](/docs/contribute/style/style-guide/)に従っていますか？
- もっと短くしたり単純な文に書き換えられる長い文はありませんか？
- 箇条書きやテーブルでもっとわかりやすく表現できる長いパラグラフはありませんか？
### コンテンツ
- 同様のコンテンツがKubernetesのサイト上のどこかに存在しませんか？
- コンテンツが外部サイト、特定のベンダー、オープンソースではないドキュメントなどに過剰にリンクを張っていませんか？
### ウェブサイト
- PRはページ名、slug/alias、アンカーリンクの変更や削除をしていますか？ その場合、このPRの変更の結果、リンク切れは発生しませんか？ ページ名を変更してslugはそのままにするなど、他の選択肢はありませんか？
- PRは新しいページを作成するものですか？ その場合、次の点に注意してください。
- ページは正しい[page content type](/docs/contribute/style/page-content-types/)と関係するHugoのshortcodeを使用していますか？
- セクションの横のナビゲーション(または全体)にページは正しく表示されますか？
- ページは[Docs Home](/docs/home/)に一覧されますか？
- Netlifyのプレビューで変更は確認できますか？ 特にリスト、コードブロック、テーブル、備考、画像などに注意してください。
### その他
PRに関して誤字や空白などの小さな問題を指摘する場合は、コメントの前に`nit:`と書いてください。こうすることで、PRの作者は問題が深刻なものではないことが分かります。