zaki work log

作業ログやら生活ログやらなんやら

Kubernetes日本語ドキュメント(kubeadm部分)で初めてのOSSコントリビュートした話

Kubernetes日本語化プロジェクトの翻訳お手伝いで、初めてOSSへのコントリビュートをしてみたのでその時の話について。

きっかけ

zaki-hmkc.hatenablog.com

ここで一度kubeadmを使った高可用性クラスタは構築してたけど、日本語ドキュメントの内容が微妙に古いなぁとは感じていて

zaki-hmkc.hatenablog.com

ここで登壇したときに「ドキュメント翻訳のお手伝いしたいな」と思ってました。

そうしたところに、

週末ということもあり、いいタイミングでお手伝いしたいと思っていたドキュメントも対象になってたので、手を挙げてみることにしました。

担当のアサイ

私が担当したのはこのIssueで、v1.17の「kubeadmを使用した高可用性クラスターの作成」です。

github.com

唐突に/assignとIssueにコメントをpostすれば担当になれます。

今回の私のミッションは、(v1.17の)「kubeadmを使用した高可用性クラスターの作成」の日本語ドキュメントの内容がアップデートされていないため、オリジナルの英語版v1.17ドキュメントに沿った内容にアップデートする、です。

github.com

作業の流れ

Kubernetesのドキュメント翻訳の流れとしては、まずはこのページ。

kubernetes.io

今回は「翻訳対象のIssueが既にある場合」で「既存ページの修正の場合」でした。

ということで、GitHub的に大まかな流れは以下の通り。

  1. 自分のリポジトリへfork
  2. (ローカルにcloneして)内容を更新する
  3. 作業完了したらPull Requestを送る

わかってれば当然なんだけど、GitLabもGitHubもリモートGitリポジトリとIssue管理としてしか使ってなかったので、スタートラインに立つまでにだいぶ戸惑いました(inductorさんサポートありがとうございました)

CLAの署名

また、Pull Requestを送ったあとにマージされるためには、Linux Foundation IDの作成・GitHubとの連携が必要ですが、こちらのページに詳しく書かれているのでその通りアカウント設定すればOKでした。

qiita.com

英語の住所を書く必要があるので、過去に海外通販したときのメールの控えを引っ張り出しました(笑)

アカウントを作成するとこんな感じになり、

f:id:zaki-hmkc:20200725225638p:plain

CLAの署名まで完了すると以下のようになります。(これで準備OKだけど、この署名の作業はPRを送るタイミングでも良いとのこと。私はfork前に最初にやっちゃいましたが)

f:id:zaki-hmkc:20200725230042p:plain

初めてのfork

そんなことも知らないの?って感じだったけど、ここから。

f:id:zaki-hmkc:20200725235743p:plain

ボタン押下すると、コピーが自分のリポジトリとして作成される。

f:id:zaki-hmkc:20200725235850p:plain

コミットメッセージ

(prefixなどの)明示的なルールはないみたいでしたが、グローバルなOSSなので英語でコミットするのがお作法となってました。

ちなみに個人PJでのコミットメッセージはこちらの「ライト版」を普段はベースにしています。

qiita.com

(改めて見てみたら、私"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 >}}とかのコマンド記述の表示確認ができます。

f:id:zaki-hmkc:20200726004252p:plain

本家側の変更の取り込み

作業中にオリジナルのドキュメントファイルに更新があったため、cloneしたローカルのリポジトリに変更を取り込みました。

qiita.com

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、ここから。

f:id:zaki-hmkc:20200726000032p:plain

何を書けば良いかよくわからず、最終的にこんな感じに。

f:id:zaki-hmkc:20200726000142p:plain

この部分は間違えが無いように何度も目視チェックしました。

f:id:zaki-hmkc:20200726000405p:plain

これでPull Request作成すると自分のホーム画面にこんなアクティビティが追加されました。

レビュー

PRするとレビュワーの方が内容をチェックしてくれます。
実は指摘事項があったらその修正を行って再度PRを作成するんだと思ってたんですが、GitHubの機能でレビュワーの方が直接変更の提案をpostして、それで良ければPRの作成者(つまり私)が変更の提案を取り入れる「Commit suggestion」というものがあり、(多分)軽微な修正であればこれでだいたい済んでしまうようです。

これとかこれとか

docs.github.com

devblog.thebase.in

PRの中で、変更点に対してコメントと変更の提案をまとめて確認できて、取り入れるときも「Commit suggestion」を押下すればいいのでとてもスムーズ。
世の中のドキュメントはすべてtext/plainで書いて、この要領でレビューと修正が行われればものすごく効率挙がりそう。

f:id:zaki-hmkc:20200726001753p:plain

ちなみにこの「Commit suggestion」を押下すれば良いということに気付かず、PR後割とすぐにチェック頂いていたのに、取り込んだのは何時間か間が空いた後でした(スミマセン)

その後、botのコメントに従ってレビュワーの方のアカウントを/assignし、レビュー完了するのをしばし待ちました。

マージ

f:id:zaki-hmkc:20200726005324p:plain

2,3日後、無事にマージされ、Issueもクローズとなりました。お疲れさまでした!

ちなみに私の作業自体は、土曜の午後に「やります!」と宣言して、その間ガッツリ(プロ野球中継やドラマを見ながら)作業して、PR送ったのは日曜の夜でした。

ファイルはこちら

今後の展望など

  • 2つ目のPRにチャレンジ
  • Issueを作成するところからやってみる
  • もう少しダメ出しくらってレビュワーの方とやり取りしてみる
  • この話をネタにk8sjpなどでLTする
  • Ansibleにもコントリビュートしてみたい

inductorさん曰く「仕事ってわけじゃないので、間違えても大丈夫なんで『習うより慣れろ』で」とのこと。
本当にお世話になりました!


masterにもマージされました!

kubernetes.io