Kubernetes日本語化プロジェクトの翻訳お手伝いで、初めてOSSへのコントリビュートをしてみたのでその時の話について。
- きっかけ
- 担当のアサイン
- 作業の流れ
- CLAの署名
- 初めてのfork
- コミットメッセージ
- 翻訳で困ったとき
- ローカルでの動作確認
- 本家側の変更の取り込み
- 初めてのPull Request
- レビュー
- マージ
- 今後の展望など
きっかけ
ここで一度kubeadmを使った高可用性クラスタは構築してたけど、日本語ドキュメントの内容が微妙に古いなぁとは感じていて
ここで登壇したときに「ドキュメント翻訳のお手伝いしたいな」と思ってました。
そうしたところに、
Kubernetesの日本語化プロジェクトでは「OSS初めての方向け」のIssueを開いています。まだ未アサインのものも5つほどあります。ぜひこの機会にチャレンジしてみてください!https://t.co/WkzS3Tz32j
— inductor (@_inductor_) 2020年7月18日
週末ということもあり、いいタイミングでお手伝いしたいと思っていたドキュメントも対象になってたので、手を挙げてみることにしました。
担当のアサイン
私が担当したのはこのIssueで、v1.17の「kubeadmを使用した高可用性クラスターの作成」です。
唐突に/assign
とIssueにコメントをpostすれば担当になれます。
今回の私のミッションは、(v1.17の)「kubeadmを使用した高可用性クラスターの作成」の日本語ドキュメントの内容がアップデートされていないため、オリジナルの英語版v1.17ドキュメントに沿った内容にアップデートする、です。
作業の流れ
Kubernetesのドキュメント翻訳の流れとしては、まずはこのページ。
今回は「翻訳対象のIssueが既にある場合」で「既存ページの修正の場合」でした。
ということで、GitHub的に大まかな流れは以下の通り。
- 自分のリポジトリへfork
- (ローカルにcloneして)内容を更新する
- 作業完了したらPull Requestを送る
わかってれば当然なんだけど、GitLabもGitHubもリモートGitリポジトリとIssue管理としてしか使ってなかったので、スタートラインに立つまでにだいぶ戸惑いました(inductorさんサポートありがとうございました)
CLAの署名
また、Pull Requestを送ったあとにマージされるためには、Linux Foundation IDの作成・GitHubとの連携が必要ですが、こちらのページに詳しく書かれているのでその通りアカウント設定すればOKでした。
英語の住所を書く必要があるので、過去に海外通販したときのメールの控えを引っ張り出しました(笑)
アカウントを作成するとこんな感じになり、
CLAの署名まで完了すると以下のようになります。(これで準備OKだけど、この署名の作業はPRを送るタイミングでも良いとのこと。私はfork前に最初にやっちゃいましたが)
初めてのfork
そんなことも知らないの?って感じだったけど、ここから。
ボタン押下すると、コピーが自分のリポジトリとして作成される。
コミットメッセージ
(prefixなどの)明示的なルールはないみたいでしたが、グローバルなOSSなので英語でコミットするのがお作法となってました。
ちなみに個人PJでのコミットメッセージはこちらの「ライト版」を普段はベースにしています。
(改めて見てみたら、私"remove"は使ってなくて"add","update","fix"ばかりだ。。)
翻訳で困ったとき
基本的には過去バージョンのドキュメントと、新しい部分もGoogle翻訳などを利用すれば問題無いはず。
それでも良い感じの日本語にならないときは、今回はSlackでinductorさん相談しました。
下手に考えるよりもそちらの方が早いし確実でした。
ただこの手の相談・質問を逐一していると、質問する側(私)はともかく対応してくれる方は大変なので「一旦やりきってからPRで相談」が良いようです。(今回は少なかったので、訳についての相談は1回きりでしたが)
ちなみに作業中にうまく作文できなかったのは、以下の2フレーズ
- Quote this line if you are using external etcd
- スクリプト中のコメントに出てくるけど、「この行を引用」とは…
- Stacked hogehoge
- 日本語版既存ドキュメントだと「積み重なったコントロールプレーンノード」だけど、それで大丈夫?みたいな…
- stacked control plane nodes とか
- stacked etcd とか
- 日本語版既存ドキュメントだと「積み重なったコントロールプレーンノード」だけど、それで大丈夫?みたいな…
ローカルでの動作確認
Kubernetesのドキュメントは、ローカルでの動作確認にHugoというツールが使用されています。
使い方はREADMEにも載っているので、内容の通りバイナリをインストールして実行すれば良い…のですが、もっと簡単にmake
を使ってDockerでも動作確認ができます。
まずREADMEにも書かれている通り
git submodule update --init --recursive
でGitのSubmodule設定をしてから
$ make container-image && make container-serve
すればOKです。 私の環境はroot権限必要なので、実際はこんな感じ。
[zaki@cloud-dev website]$ sudo make container-image docker build . \ --network=host \ --tag kubernetes-hugo \ --build-arg HUGO_VERSION=0.70.0 Sending build context to Docker daemon 3.584kB Step 1/7 : FROM alpine:latest ---> a24bb4013296 Step 2/7 : LABEL maintainer="Luc Perkins <lperkins@linuxfoundation.org>" ---> Using cache ---> 3b4310c1ed93 Step 3/7 : RUN apk add --no-cache curl git openssh-client rsync build-base libc6-compat ---> Using cache ---> c9bdf4c53f67 Step 4/7 : ARG HUGO_VERSION ---> Using cache ---> c9ac98a4089c Step 5/7 : RUN mkdir -p /usr/local/src && cd /usr/local/src && curl -L https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_Linux-64bit.tar.gz | tar -xz && mv hugo /usr/local/bin/hugo && addgroup -Sg 1000 hugo && adduser -Sg hugo -u 1000 -h /src hugo ---> Running in af88c864ab9a % Total % Received % Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed 100 650 100 650 0 0 1666 0 --:--:-- --:--:-- --:--:-- 1666 100 13.8M 100 13.8M 0 0 2926k 0 0:00:04 0:00:04 --:--:-- 3336k Removing intermediate container af88c864ab9a ---> 4dcd223e93b5 Step 6/7 : WORKDIR /src ---> Running in 7a1661640eb8 Removing intermediate container 7a1661640eb8 ---> 7641c012146e Step 7/7 : EXPOSE 1313 ---> Running in c2b1ea5c416f Removing intermediate container c2b1ea5c416f ---> 376bc09a5beb Successfully built 376bc09a5beb Successfully tagged kubernetes-hugo:latest
[zaki@cloud-dev website]$ sudo make container-serve docker run --rm --interactive --tty --volume /home/zaki/src/tmp/website:/src --mount type=tmpfs,destination=/src/resources,tmpfs-mode=0755 -p 1313:1313 kubernetes-hugo hugo server --buildFuture --bind 0.0.0.0 | EN | ZH | KO | JA | FR | IT | DE | ES | PT | ID | RU | VI | PL | UK -------------------+------+------+------+------+------+------+------+------+------+------+------+------+------+------- Pages | 1105 | 762 | 368 | 250 | 237 | 53 | 104 | 160 | 51 | 183 | 109 | 63 | 54 | 64 Paginator pages | 33 | 4 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 Non-page files | 432 | 354 | 215 | 236 | 59 | 25 | 21 | 27 | 25 | 75 | 24 | 13 | 9 | 28 Static files | 1098 | 1098 | 1098 | 1098 | 1098 | 1098 | 1098 | 1098 | 1098 | 1098 | 1098 | 1098 | 1098 | 1098 Processed images | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 Aliases | 8 | 4 | 1 | 0 | 0 | 0 | 0 | 0 | 0 | 1 | 0 | 0 | 0 | 0 Sitemaps | 2 | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1 | 1 Cleaned | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 | 0 Built in 19560 ms Watching for changes in /src/{archetypes,assets,content,data,i18n,layouts,static,themes} Watching for config changes in /src/config.toml, /src/themes/docsy/config.toml Environment: "development" Serving pages from memory Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender Web Server is available at http://localhost:1313/ (bind address 0.0.0.0) Press Ctrl+C to stop
これで、http://localhost:1313/ にアクセスすれば、手元で更新している内容のKubernetesドキュメントサイトにアクセスでき、{{< caution >}}
とかのコマンド記述の表示確認ができます。
本家側の変更の取り込み
作業中にオリジナルのドキュメントファイルに更新があったため、cloneしたローカルのリポジトリに変更を取り込みました。
forkした先のリポジトリ(= clone元のリポジトリ)はorigin
という名前で登録されているため、fork元のリポジトリを新たにupstream
という名前で追加し、そこからfetch
してrebase
しています。
[zaki@cloud-dev website]$ git remote add upstream https://github.com/kubernetes/website.git [zaki@cloud-dev website]$ git remote -v origin https://github.com/zaki-lknr/website.git (fetch) origin https://github.com/zaki-lknr/website.git (push) upstream https://github.com/kubernetes/website.git (fetch) upstream https://github.com/kubernetes/website.git (push) [zaki@cloud-dev website]$ git branch * dev-1.17-ja.3 [zaki@cloud-dev website]$ git fetch upstream remote: Enumerating objects: 85, done. remote: Counting objects: 100% (85/85), done. remote: Compressing objects: 100% (21/21), done. remote: Total 117 (delta 73), reused 71 (delta 64), pack-reused 32 Receiving objects: 100% (117/117), 25.82 KiB | 0 bytes/s, done. Resolving deltas: 100% (87/87), completed with 27 local objects. From https://github.com/kubernetes/website * [new branch] Case-nit-for-k8s -> upstream/Case-nit-for-k8s * [new branch] daminisatya-patch-1 -> upstream/daminisatya-patch-1 * [new branch] dev-1.17 -> upstream/dev-1.17 * [new branch] dev-1.17-bad -> upstream/dev-1.17-bad * [new branch] dev-1.17-it.1 -> upstream/dev-1.17-it.1 * [new branch] dev-1.17-ja.3 -> upstream/dev-1.17-ja.3 * [new branch] dev-1.17-ko.8 -> upstream/dev-1.17-ko.8 * [new branch] dev-1.17-pl.1 -> upstream/dev-1.17-pl.1 * [new branch] dev-1.17-ru.1 -> upstream/dev-1.17-ru.1 * [new branch] dev-1.17-test -> upstream/dev-1.17-test * [new branch] dev-1.17-uk.1 -> upstream/dev-1.17-uk.1 * [new branch] dev-1.18 -> upstream/dev-1.18 * [new branch] dev-1.18-ar.1 -> upstream/dev-1.18-ar.1 * [new branch] dev-1.18-it.1 -> upstream/dev-1.18-it.1 * [new branch] dev-1.18-ko.6 -> upstream/dev-1.18-ko.6 * [new branch] dev-1.18-ko.7 -> upstream/dev-1.18-ko.7 * [new branch] dev-1.18-ko.8 -> upstream/dev-1.18-ko.8 * [new branch] dev-1.19 -> upstream/dev-1.19 * [new branch] es/fix-rc-typo -> upstream/es/fix-rc-typo * [new branch] feature/merge -> upstream/feature/merge * [new branch] fix/typo-tasks-index -> upstream/fix/typo-tasks-index * [new branch] ingress-in-vi -> upstream/ingress-in-vi * [new branch] kbarnard10-patch-1 -> upstream/kbarnard10-patch-1 * [new branch] master -> upstream/master * [new branch] release-1.10 -> upstream/release-1.10 * [new branch] release-1.11 -> upstream/release-1.11 * [new branch] release-1.12 -> upstream/release-1.12 * [new branch] release-1.13 -> upstream/release-1.13 * [new branch] release-1.14 -> upstream/release-1.14 * [new branch] release-1.15 -> upstream/release-1.15 * [new branch] release-1.16 -> upstream/release-1.16 * [new branch] release-1.17 -> upstream/release-1.17 * [new branch] release-1.4 -> upstream/release-1.4 * [new branch] release-1.5 -> upstream/release-1.5 * [new branch] release-1.6 -> upstream/release-1.6 * [new branch] release-1.7 -> upstream/release-1.7 * [new branch] release-1.8 -> upstream/release-1.8 * [new branch] release-1.9 -> upstream/release-1.9 * [new branch] remove_404_robots -> upstream/remove_404_robots * [new branch] remyleone-patch-1 -> upstream/remyleone-patch-1 * [new branch] remyleone-patch-2 -> upstream/remyleone-patch-2 * [new branch] revert-16869-patch-2 -> upstream/revert-16869-patch-2 * [new branch] revert-18215-master-zh-fix-links -> upstream/revert-18215-master-zh-fix-links * [new branch] what-is-k8s -> upstream/what-is-k8s * [new branch] xichengliudui-patch-2 -> upstream/xichengliudui-patch-2 * [new branch] xichengliudui-patch-3 -> upstream/xichengliudui-patch-3 [zaki@cloud-dev website]$ git rebase upstream/dev-1.17-ja.3 First, rewinding head to replay your work on top of it... Fast-forwarded dev-1.17-ja.3 to upstream/dev-1.17-ja.3. [zaki@cloud-dev website]$
普段はmerge
しか使ってなくて、rebase
を使った変更の取り込みはイマイチ分かってないけど、rebase
使ってねと言われたのでそうしてみました。。
初めてのPull Request
そんなことも(ry、ここから。
何を書けば良いかよくわからず、最終的にこんな感じに。
この部分は間違えが無いように何度も目視チェックしました。
これでPull Request作成すると自分のホーム画面にこんなアクティビティが追加されました。
なるほど、こうなるのか pic.twitter.com/4al9i1hEtC
— z a k i (@zaki_hmkc) 2020年7月19日
レビュー
PRするとレビュワーの方が内容をチェックしてくれます。
実は指摘事項があったらその修正を行って再度PRを作成するんだと思ってたんですが、GitHubの機能でレビュワーの方が直接変更の提案をpostして、それで良ければPRの作成者(つまり私)が変更の提案を取り入れる「Commit suggestion」というものがあり、(多分)軽微な修正であればこれでだいたい済んでしまうようです。
PRの中で、変更点に対してコメントと変更の提案をまとめて確認できて、取り入れるときも「Commit suggestion」を押下すればいいのでとてもスムーズ。
世の中のドキュメントはすべてtext/plainで書いて、この要領でレビューと修正が行われればものすごく効率挙がりそう。
ちなみにこの「Commit suggestion」を押下すれば良いということに気付かず、PR後割とすぐにチェック頂いていたのに、取り込んだのは何時間か間が空いた後でした(スミマセン)
その後、botのコメントに従ってレビュワーの方のアカウントを/assign
し、レビュー完了するのをしばし待ちました。
マージ
2,3日後、無事にマージされ、Issueもクローズとなりました。お疲れさまでした!
Mergedに!なりました!https://t.co/7C53ocIGmE
— z a k i (@zaki_hmkc) 2020年7月22日
ちなみに私の作業自体は、土曜の午後に「やります!」と宣言して、その間ガッツリ(プロ野球中継やドラマを見ながら)作業して、PR送ったのは日曜の夜でした。
今後の展望など
- 2つ目のPRにチャレンジ
- Issueを作成するところからやってみる
- もう少しダメ出しくらってレビュワーの方とやり取りしてみる
- この話をネタにk8sjpなどでLTする
- Ansibleにもコントリビュートしてみたい
inductorさん曰く「仕事ってわけじゃないので、間違えても大丈夫なんで『習うより慣れろ』で」とのこと。
本当にお世話になりました!
masterにもマージされました!
反映されてるー » kubeadmを使用した高可用性クラスターの作成 | Kubernetes https://t.co/6OL62eX5qq
— z a k i (@zaki_hmkc) 2020年8月7日