テスト・QAエンジニアのみなさんはOSS活動をしたくてたまらないのではないかと思います。
とはいえ、なかなか普段からゴリゴリコードを書いたりしない、本業が開発者ではないという場合は、OSSのバグを修正したり機能を追加したりといったコントリビュート方法はハードルが高いですよね。
ということで、今回はもう少し身近な「日本語ドキュメントの翻訳に貢献する」という切り口でOSSにコントリビュートしてみましょうよ、という記事です。私自身毎日のようにやっている、というわけでは全くないですが、思い立ったときに少しでもやってみると楽しいです。
OSSへのコントリビュート
前段として、そもそもコントリビュートってなんぞやというところから話を始めます。普段エンジニアとして仕事をするにあたって、もはや当たり前のようになんらかのOSSを使っていると思います。
コントリビュート（貢献）とは
そんなOSSですが、便利に使える裏では世の中の誰かが作り、維持してくれているから使えます。そこで、ただで使うだけではなく、何かしらOSSおよびコミュニティの役に立つことをする、というのがコントリビュート（貢献）です。
貢献する方法は実は色々あります。
- コミュニティにお金を寄付する
- イベント運営する
- ブログを書いたり、技術情報を発信したりする
- 機能追加や修正などを行う
などなど。コードを全く書けないけれども何かしら感謝の意を示したい、OSSの存続に役に立ちたい、という場合はダイレクトに寄付をするというのも手です。そのほか、大きなくくりでは「コミュニティを盛り上げる」というのもひとつの貢献の仕方です。
この記事では4番目のように、機能追加や修正など直接編集をする（＝プルリクエストを送る）形でのコントリビュートについて説明します。
機能追加や修正などで貢献する動機
もちろん人によって様々ですが、貢献する方は色々な動機で行っています。
- 気持ち的な理由
- 普段使っているので、恩返しをしたい
- タダ乗りするだけじゃなくて何かしら役に立つべき
- そのOSSが好きすぎるので体が勝手に動く
- 自己研鑽的理由
- ソースを読んだり、直したり、プルリクを送ったりすると、技術力の向上につながる
- 打算的理由
- 就職転職に有利だと思ったから
- なんかかっこいい、エンジニアやってる感がある
このへんの動機に優劣はないので、何かご自身の思いに近いものがあれば、今回行動を起こすきっかけにしてみてください。
一般的な作法
不特定多数の方が関わる前提のOSSは、コントリビュートするにもルールが定められています。それらを知らずに勝手な方法でやると迷惑が掛かるため、最低限のお作法は理解して臨みましょう。
1. とにかくまずはCONTRIBUTING.mdを読む
GitHubでリポジトリを公開している多くのOSSでは、CONTRIBUTING.mdというファイルがあります。
これは「このOSSプロジェクトに貢献するためのルールとやりかた」が書いてあるものです。必ず目を通して、記載のやり方に従って貢献をしましょう。
↑SeleniumHQ/seleniumhq.github.io: Official Selenium website and documentationの例
CONTRIBUTING.mdの内容はOSSによって多少違いがありますが、一般的には以下のような内容が書かれています。
- 貢献したい人がソースをローカルに落として変更してプルリクを送るまでの一般的な流れ
- プルリクに書くべき内容
- これはGitHubでテンプレ化されていることがほとんど
- 初心者はこのタグがついたIssueがいいよ！的なおすすめ
- 機能のリクエストをIssueで書くのは良いけど過去ログはちゃんと読みなさい、的注意など
2. 貢献するポイントを探す
もともと「こんな機能を足したい」とか「ここがおかしいから直したい！」という方もいますが本記事の対象外なので、ここでは「コントリビュートしてみたい」が先にあって、何をするかを後から探すパターンで説明します。
貢献するポイントを探すには、大まかに2通りあります。
- GitHubのIssueを見て、既存のバグや直すべきポイントを拾って対応する
- 自分がOSSを使っていて気づいた問題でIssueに上がっていないものをやる
前者は（初心者向けのIssueだよ！と書いてあったとしても）難しいものも多いので、ここで心折れるくらいなら後者のパターンで超簡単＆軽微な修正を行うのは全然アリです。まずは貢献度合いや難易度よりも、お作法に慣れることを第一にやっていきましょう。
Seleniumのドキュメントにコントリビュートしてみよう
コントリビュートするにあたってのお作法がなんとなくわかったところで、実際のOSSプロジェクトにコントリビュートしてみましょう。今回はSeleniumのドキュメントを対象に説明します。
ソースコードの修正や機能追加に比べるとハードルが低いため初心者にとってもチャレンジしやすい、と思っています。
また、実際にSeleniumのドキュメントサイト上でも、日本語訳が求められています。
Page being translated from English to Japanese. Do you speak Japanese? Help us
to translate it by sending us pull requests!
大まかな流れは以下です。
①SeleniumWebDriverに貢献するときのルールを知る
②環境構築をする
③やることを決める
④変更を加える
⑤プルリクエストを送る
前提事項
このあとの説明にあたってそれなりに端折っています。
①SeleniumWebDriverに貢献するときのルールを知る
まずは一般的なお作法でも見てきたように、CONTRIBUTING.mdをチェックしましょう。
リポジトリはこちらです＞SeleniumHQ/seleniumhq.github.io: Official Selenium website and documentation
CONTRIBUTING.mdを見てみると、以下のように書いてあります。
Contributing to the Selenium site and docs
Please follow this link for all the contribution details.
このリポジトリは、コントリビュートするにあたっての注意事項がCONTRIBUTING.mdではなく別のリンク先に書いてあるということなので、指示通り開いてみます。
リンクされている先はこちら＞Contributing to the Selenium site & documentation | Selenium
ここがコントリビュートする際の注意事項が書いてあるページです。右上の「English」のプルダウンを選んで、日本語に変更しましょう。
日本語になりました。ここを読んでいくことにします。
ただし、このSeleniumのドキュメントのリポジトリにおいては、README.mdにも一部必要な事項が書いてありますので、そちらも参照しておきましょう。
QuickStartのあたりですね。
このSeleniumのドキュメントサイトでは、Hugoという静的サイトジェネレーターを使用している、と記載があります。
実際にドキュメントの一部を翻訳したり修正したりしたあとは、正しくサイトに反映されているか確認する必要があります。（テストエンジニアならテストには慣れていますよね）
そのためには、このHugoという静的サイトジェネレーターの環境を手元に用意しなければなりません。
この記事中でHugoについても全て書くと長くなりすぎるので、以下を参考にやってみてください。
- 公式ドキュメント：Installation | Hugo
- QuickStartに記載の手順（Other setup options | Docsy）
ここではHugoの環境構築が出来たものとして、本筋であるコントリビュート方法の理解に進んでいきましょう。
Seleniumのサイトとドキュメントに貢献する | Seleniumでは、以下の8ステップで説明されています。
- フォーク
- ブランチの作成
- 変更を加える
- コミット
- リベース
- プッシュ
- 統合
初めての場合少しややこしいところもあるので、上記の流れは踏襲しつつも理解が易しい（と私が思う）流れでこのあと説明していきます。
②環境構築をする
実際にサイトを修正できるよう、ローカルにSeleniumのドキュメントサイトが動く状態にしましょう。
まずはリポジトリをForkします。コントリビュート方法のドキュメントに記載されているようにコマンドラインで行ってもいいですし、GitHubの画面上でForkするのも簡単で良いですね。
※私は既に一度Forkしているので Your existing forks と書かれていますが、まだの方は表示が異なります。new forkを作成しましょう。
③やることを決める
指定された手順であれば「ブランチの作成」になるわけですが、ブランチを作るにはそもそも「何をコントリビュートするのか」を決めねばなりません。今回のSeleniumのドキュメントの場合、メニュー右上を「日本語」にしたのに英語のままになっている箇所が多数あります。これらを（部分的にでも）翻訳するというのもアリです。他の点としては、Markdown記法が正しく反映されていない箇所や、画像のリンクが切れている箇所など、ちょっとした問題が（この記事執筆時点では）たくさん残っています。それらのちょっとした問題の中から、修正できそうなポイントを探すのも良いでしょう。
今回は私が過去に行った、画像のリンクが間違っていて正しく表示されない、という問題を修正する例で説明します。
↑「テストフレームワーク」の画像が出ていません。もう直してしまったので今では正しく表示されていますが、該当のページはこちらです。＞コンポーネントを理解する | Selenium
本記事執筆時点で簡単に貢献できそうな点として、たとえばいま見ているSeleniumのサイトとドキュメントに貢献する | Selenium中に、Markdownが正しく反映されていない箇所があります。
_Pull Request_を押し
という箇所は、本当であれば
Pull Request を押し
のように斜体で表示されているべきところです。お一人限定にはなりますが、こうした小さいところからでもコントリビュートは可能です。
④変更を加える
では、実際に修正をしていきましょう。
まずはブランチを切ります。ブランチを切る際には、どんな修正なのかの概要がわかる名前が良いでしょう。
本記事執筆時に他の方がPull Requestを送っているブランチ名は、たとえば
- update-console-log-python
- add-js-run-comment
などです。中にはpatch-2などもありますが、個人的には上に挙げたような名前をつけるほうがベターと考えています。
先の画像のリンク修正について、私はfix-broken-link-on-components-jaというブランチ名にしました。良い名前かどうかはアレですが、怒られはしませんでした。
ブランチを作成したら、今度はソースを修正していきます。
画像に問題があったページはコンポーネントを理解する | Seleniumで、これに対応するファイルは以下でした。URLとフォルダ構成がほぼ一致しているので、わかりやすいですね。
今回は画像のリンクを直すだけなので、修正は以下のように行いました。日本語以外のページは正しかったので、英語ページのリンクをそのまま持ってきています。
誤
/images/documentation/webdriver/remote_comms_test_frameworkserver.png
正
/images/documentation/webdriver/test_framework.png
修正ができたら、ローカルでサイトをビルドして表示を確認します。
問題なく画像が表示されました。この状態で、forkしたリポジトリのブランチにPushします。
⑤プルリクエストを送る
自分がforkしたほうのリポジトリからプルリクを送りましょう。GitHubの画面上にCompare & pull requestというボタンが出てくるので、ここからできます。
プルリクエストの本文はテンプレートがあるので、基本的には迷いません。だた、ドキュメントの翻訳や軽微な修正の場合は、本文を書くにしても簡素になりがちで、不安に思うかもしれません。
ここは心配不要で、レビューする側も長々と書かれているよりかはシンプルにまとまっていたほうが意味がわかりやすくて良い、と思いましょう。
英語で書く必要があるので、適宜DeepLやGoogle翻訳の力を借りましょう。（DeepLのEnglish->Japaneseはわりと謎の訳をすることもあるので、確認をお忘れなく。）
]
プルリクエストを送るとGitHub上で自動でチェック処理が走ります。人間が確認をする以前の問題はここで弾かれます。画面上では"Merging is blocked"と表示されて「なにかやらかしたか！？」と思ってしまうかもしれませんが、大丈夫です。自動チェックが終わっていないからなので、この時点では問題ありません。
しばらくすると、レビュワーによる確認が行われて、問題なければマージされます。運が良ければ数時間で確認されることもありますが、数日はかかるものと思って気長に待ちましょう。
マージされると、プルリクエストのステータスがMergedになります。
おめでとうございます。ここまでで、Seleniumのドキュメントにコントリビュートが出来たことになります。
Contributors to SeleniumHQ/seleniumhq.github.ioに乗っていることを確認してみましょう。
まとめ
OSSコントリビュートとは、のさらっとした説明から、Seleniumのドキュメントサイトにコントリビュートする流れまでを説明しました。
普段テスト自動化などでSeleniumに触れているけれどもOSSコントリビュートはしたことがない、という場合は、ドキュメントサイトは良いターゲットだと思うので、ぜひチャレンジしてみてください。