OSSコントリビュータになろう ― Deno編

公開:2020/12/24
更新:2020/12/31
8 min読了の目安(約7700字IDEAアイデア記事

deno illust
Copyright (c) 2018-2020 the Deno authors. MIT License.

この記事は Deno Advent Calendar 2020 24日目の記事です。

23日目は -> (あとで埋める)
25日目は -> Deno が Node.js に依存しなくなった

はじめに

こんにちは、@magurotuna です。

2020年ももうそろそろ終わりですね。みなさんはどのような1年を過ごされたでしょうか?
僕は、初めての転職をしたり、OSSコントリビュートを始めたり、といった1年でした。
OSSコントリビュートに関しては、去年までは「凄腕のエンジニアがやるものであって、平凡なエンジニアである僕はその恩恵に預かるだけ……」と思っていましたが、いざやってみると、まったくそのようなことはなく、さまざまな方面からOSSに貢献することができるということが分かりました。

そこでこの記事では、例として Deno を取り上げて、どのようにすればコントリビュートすることができるのかを実例を交えながら紹介していきたいと思います。

issueでバグを報告することや、新機能に関してユーザー目線からの意見を述べることなども間違いなく「貢献」なのですが、本記事中では コードやドキュメントを修正すること を指して便宜的に コントリビュート および 貢献 という用語を用います。

対象読者

  • OSSにコントリビュートしてみたいが、やり方が分からない人
  • Deno にコントリビュートしてみたい人
  • OSSへのコントリビュートを手段ではなく目的にしたい人(とにかくコントリビュートをしてみたいんだ、という人)

Deno を実例として挙げますが、Deno に限らず、一般的なOSSであればある程度参考とすることができると思います。

コントリビュートするまでの流れ

一般的に、以下のような流れを辿ることになると思います。

  1. コントリビュートしたいプロジェクトを見つける。(あるいはコントリビュートしやすそうなプロジェクトを見つける、という場合もある)
  2. issues を眺めて、初見でも対応することができそうなものを探す。good first issue というラベルが付いているものを見てみるのが手っ取り早いです。
  3. この修正をやってみたいです!と宣言する
  4. リポジトリを fork する
  5. コードを修正する
  6. Pull Requestを立て、レビューしてもらう
  7. 🎉マージされる🎉

順に細かく説明します。

1. コントリビュートしたいプロジェクトを見つける

どこにコントリビュートするのかを決めないと話が進まないので、まずはこれを決めます。
ただ、とにかくコントリビュートをするというのが目的であるならば、「コントリビュートしやすそうなところを選ぶ」のが重要になります。
個人的には、以下の条件が揃っているとコントリビュートしやすいと思います:

  • 技術的に興味のもてるプロジェクトである
  • コントリビュートしたい人向けのドキュメントが充実している(開発の始め方、テストの走らせ方、コードのアーキテクチャがドキュメントにまとまっている、など)
  • コードが複雑すぎず、がんばれば処理の流れを読み解くことができる
  • コミュニティが活発である(issueやPRへの対応が早く、スムーズに事が進みます)
  • good first issue が付いた issue で、まだ他の人が着手していないものが多くある
  • メンテナに日本人がいて、日本語でやりとりできる

言語の壁について

最後の「日本語でやりとりできる」を少し取り上げます。日本語でやり取りができれば心理的なハードルはかなり下がると思いますが、とはいえOSSの世界は英語が共通言語です。日本人の方とやりとりをする場合であっても言語は英語、ということもままあります。

しばらく英語でやりとりしているうちに慣れてくるとは思いますが、最初のハードルを下げるためにも、機械翻訳を積極的に活用するのがおすすめです。

僕の場合は、

  • 自力で英語で書いてみる
  • 書いた英語をDeepLやGoogle翻訳で日本語に訳してみる
  • 違和感のない日本語になっているかチェックする

という手順を踏んでいました。

最初から日本語で書いてしまって、機械翻訳で英語にするというのでも問題ないと思います。例えば、Pull Requestを立てるときの本文として、以下のような内容にしたいというケースを考えてみます。

このPRでは、関数 foo の内部処理を修正し、xxxというケースでも正しい結果が返ってくるようにしました。

これをそのままDeepLで翻訳にかけてみると、以下のような結果が出力されました。

This PR fixes the internal processing of the function foo so that the correct result is returned even in the case xxx.

問題なく伝わる英文になっていると思います。
OSSコントリビュートはしてみたいけど、英語に自信がないから……という理由だけでコントリビュートを諦めてしまうのは、あまりにも惜しいです。機械翻訳ツールを使って言語の壁を取っ払いましょう。

2. issue を探す

リポジトリの目星がついたら、続いてどのような issue が立っているかを眺めてみましょう。初心者でもできる手軽な issue には good first issue というラベルを付ける文化があるので、このラベルをまずチェックするのが良いです。

Deno の場合、2020/12/24時点で12個の good first issue があります。
good first issues
denoland/deno にある good first issues

ただ、人気 OSS の good first issue は、コントリビュートを狙う人からの注目度が高く、すでに誰かが「私がやります!」と宣言していることが多いです。そのような場合、「やります」宣言がいつなされたかを確認してみてください。宣言日が1か月前などで、1か月の間とくに作業をしている様子がなければ、「私がやってもいいですか?」と言ってしまって問題ないと思います。

または、新しく立てられる issue を狙う、という手もあります。これをするために、リポジトリを watch するのがおすすめです。GitHub の画面右上のほうにあるこのメニューから watch 設定をすることができます。

repo watch
リポジトリを watch

リポジトリによりますが、非常に活発に開発が行われているリポジトリの場合、All Activity を watch するようにすると、とんでもない量の通知が届くようになります。メールの振り分け設定などを適切に行っておきましょう。

また、リポジトリのメンテナをフォローするのも役に立ちます。issue を見て good first issue などのラベルをつけるのはメンテナです。メンテナをフォローすると、メンテナが issue にラベルをつけたとき、GitHub 上の activity timeline に掲載されるようになります。timeline をこまめにチェックしておけば、新しく生まれる good first issue にいち早く気づくことができる可能性が高まります。

なお、good first issue はあくまでメンテナがさっと見て「これは簡単に修正できそう」と思ったものに対して付いています。メンテナの予想よりも込み入った問題で、実際には修正するのはかなり大変、ということも当然ありえます。逆に、good first issue がついていないものの中にも、簡単な issue があることもあります。

リポジトリを数ヶ月単位で watch して、プロジェクトの構造がなんとなく分かってくるようになると、「自分がこなせそうな issue はどういうものなのか」というのが直感的に分かりはじめます。いくつかのリポジトリを watch しながら、長い目で issue 探しをする、というのも良いかなと思います。

3. 「この修正をやります!」と宣言する

取り組めそうな issue を発見することができたら、「やってもいいですか?」と宣言しましょう。コントリビュートガイドのようなドキュメントに「やる前には宣言してね」と明示的に書かれているプロジェクトもありますが、書かれていないプロジェクトもあります。書かれていないプロジェクトであっても、宣言して悪いことはないと思います。"May I work on it?" などと一言コメントすれば OK です。

4. リポジトリを fork する

fork して、clone して、ブランチを切って(切らなくて良いことも多い)コードに修正を加えるための準備をしていきます。

ブランチ名に規約が定まっているOSSプロジェクトはほとんどない印象ですが、もしかしたらあるかもしれないので、コントリビュータ向けのドキュメント等を参照してください。英語を読むのが面倒だったらどんどん機械翻訳にかけましょう。

5. コードを修正する

コードを修正していきましょう。

コントリビュータ向けのドキュメントが整っているプロジェクトであれば、そのドキュメントを参照することで、動作確認の方法やテストの走らせ方、リンター、フォーマッタの適用方法などなどが分かる場合が多いです。一気にコード修正を全部終わらせてからまとめて動作確認やテストを行うと、一発ではうまく動かない場合も多いので、修正すべき内容を適度な粒度に分割した上で作業を進めていくのがおすすめです。

コードスタイルに関する規約が定まっていることもあります。ドキュメントを参照してください。
例えば Deno では以下に style_guide.md というスタイルガイドがまとまっています。例えば ファイル名にはダッシュ - ではなくてアンダースコア _ を使うこと、などの決まりごとです。

おおむね、既存のコードのスタイルにしたがっておけば間違いないと思います。郷に入っては郷に従え がキーワードです。

コードスタイルの他にも、commit の書き方にも決まりがある場合があります。こちらも明示的にルール化されているプロジェクトと、そうでないプロジェクトがあります。とりあえずは過去のコミットをざっと眺めて、どのようなスタイルのコミットメッセージになっているのかを見るのが良いと思います。

Deno の場合は、Pull Request がマージされる際に squash されるため、開発ブランチ上での commit の粒度やスタイルは自由です。
以下は自由すぎる commit を行っている様子です。
dirty commit log
自由な commit

コードを修正する中で、分からないところが出てくることもよくあります。そのような場合は、元の issue のコメントで誰かに情報を求めることになります。多くの場合は優しく教えてくれることが多いですが、忙しくてなかなか対応されないこともあります。OSS活動は基本的には 自走力 が強く求められるように思います。

Deno の場合は、コミュニティ向けに Discord サーバーが立っており、ここで質問をするとかなり素早く返答が返ってきます。コアチームメンバーの方々も常駐しておりとても心強いです。比較的大きめのプロジェクトであれば、同様にコミュニティ向けのチャットが提供されていることも多いと思うので、ぜひチェックしてみてください。

6. Pull Requestを立て、レビューしてもらう

修正が終わり、ローカルでの簡単な動作確認なども完了したら、push して Pull Request を立てましょう。
多くのプロジェクトで、Pull Reqeustのタイトルと本文についてのテンプレートが用意されていると思います。書くべき内容がまとまっているので一読し、テンプレートを埋めていきましょう。

その Pull Request によって解決される issue がある場合は、fixes #123 とか resolves #123 とか closes #123 のような文言を本文に含めることで、GitHub が自動的に issue との紐付けを行ってくれます。メンテナにとってもありがたいので、積極的に紐付けをしていきましょう。

Pull Request を立てると、勝手に CI が回りはじめることが多いです(これもプロジェクトによる)。CI が通らなかったら、エラーログを確認して、修正しましょう。

メンテナや他のコントリビュータがレビューをしてくれます。問題なさそうであれば LGTM されますが、不備がある場合は指摘がきますし、実装の意図が分かりづらかったら質問が来ると思います。機械翻訳を駆使しながら回答したり、コードを修正したりしましょう。

7. 🎉マージされる🎉

approve されたら、マージされます。おめでとうございます!!

実際のコントリビュートの例を紹介

僕が Deno にコントリビュートをしたときの流れを、以下の issue に取り組んだときのものを例として紹介します。

11月14日の2:09(日本時間)に投稿された issue です。GitHub からの通知および Discord 上でのやり取りを見てこの issue に気づき、内容を把握、これはすぐに原因が分かる気がすると直感し、2:20に「調査中です。多分これこれこういう原因だと思います。」と書き込み、修正作業を開始しました。

issue の問題そのものはすぐに修正することができて 2:26 に修正を commit したのち、2:29 に Pull Request を立てました。

commit that fixes the issue itself
2:26 の commit

実装の修正はしたものの、テストコードが不足していたので、Pull Request を立てたあとからテストコードの追加を開始しました。プロジェクトによるとは思いますが、WIP (Work in progress、作業中)の Pull Request を立ててもOKなプロジェクトであれば、進捗を早めに共有するという意味で、完成する前に Pull Request を立ててしまう、というのはアリです。

テストを書いている間に、コアチームメンバーの Bartek から 「なんか似た処理をしているメソッドがあるっぽいんだけど、これってまとめられたりしない?」(意訳)というコメントをもらいました。軽く見てみたところ、確かに同じような処理をしているので、まとめることができそうでした。このとき午前4時、さすがに眠くなったので、「明日やります:)」とコメントして寝ました。

翌日、Bartek から指摘された箇所のリファクタリングも行って、レビューをお願いしました。approve をもらって無事にマージされました(11月14日 21:05)。issue が立ってから1日経たずにマージまでいくことができました。

おわり

OSSコントリビュートの流れと実例を紹介しました。
この記事によってみなさんのOSSコントリビュートのハードルを下げることができたら嬉しいです。
年末年始、余った時間でぜひ OSS に貢献してみてください!

この記事に贈られたバッジ