deno_std で始めるゼロからの OSS contribution
これは Deno の AdventCalendar 2021 の11日目の記事です。
この記事では自分が過去に deno_std に投げた PR をもとに、OSS への contribution の第一歩として deno_std はおすすめじゃないか?という話をします。
deno_std は Deno の標準ライブラリで Deno のコアチームによってメンテナンスされており、ほとんどのコードが JavaScript/TypeScript で書かれています*1。
とはいえ、僕自身 OSS にバリバリ contribute しているわけではなく deno_std への PR はまだ2つ投げただけの初心者です🔰。OSS に興味があるけど「普段バグ踏んだりしてないし...」「よく聞くけど何していいのか分からない...」*2のようにまだ手を出せていない人がこの記事を読んで、自分にもできそう!やってみよう!となってくれるといいなと思っています。
少しだけ自己紹介をすると、都内で自社のWebサービスを開発しているエンジニアです。業務では主に Rails や TypeScript を書いています。
就職してから業務以外での開発が減り、なにか手を動かしたいなーと思って OSS 活動に手を出してみました。
OSS への貢献の種類
ひとえに OSS への貢献と言っても様々なものがあると思っています。
- ドキュメントの typo やリンク切れなどの修正
- バグ報告や自分も再現したよ!という報告
- こういった機能あったらいいななどの機能追加の提案
- バグの修正
- 機能追加
etc...
もちろんそれぞれ貢献の難易度は異なりますが、どれも大事な貢献です。
また、貢献としてよく挙げられるものは上のような例だと思いますがまずいちばん重要なことはそのツールやライブラリを使うことです。*3
deno_std を選んだ理由
僕が OSS 活動する対象として deno_std を選んだ理由は以下です。
もともと Deno 自体に興味があったが、Deno 本体は Rust で書かれている。
とはいえ Rust は全く分からないし今の所 Rust に対するモチベーションは高くない。
deno_std という標準ライブラリは TypeScript で書かれてるっぽい?
とりあえず全ての issue を Watch してみよう!
大体これが今年の8月くらいでした。 その後最初の PR を投げるまでは以下のような流れです。
どうやら collections という module に新しく API を作っているっぽいぞ? ref: https://github.com/denoland/deno_std/issues/1065
配列操作がメインなので http や byte 周りの molude よりは気軽に手が出せるかも?
というわけで投げたのがこちらの PR です。
PR を投げるまでの流れとしては、元の issue 上でまず「この機能実装したいんだけど何か気をつけたほうがいいことある?」のようなコメントをしました。
それに対して他の contributer の方が「(意訳)こういうデフォルトパラメータがあると便利かもしれないから検討してみて。あと途中で処理を短絡できるときは短絡してね。」というコメントをくれたので、早速実装に入りました。
命名や引数などで少々議論があり初めての PR がマージされるかビクビクしながら見ていましたが無事取り込まれました 🎉
実際は常に collections のように取っ掛かりやすい*4機能実装があるわけではないため、自分が Pull Request を投げることができたのはタイミング的にも運がよかったなと思っています。
現在は Deno の開発方針として Node との互換性を高めるフェーズ(?)なので Node 関連の実装が多いです。
Node 互換性の対応が落ち着いたらまた機能開発などが活発になっていくんじゃないかなぁと期待しています。
「どの OSS を選べば良いかわからない」といった人は以下の項目に当てはまる物が良いと考えています。
- 自分が普段使っている/好きな言語で書かれている
- その OSS 自体に興味がある/好き
- issue のラベルに
good first issue
のようなラベルがあり、新規参加者が貢献しやすい環境がある - (英語に自信がない場合) 日本人の開発者がいる*5
そういう点で普段 TypeScript を書いている人で特にこれがやりたいというものがない場合、 deno_std は割とおすすめできるんじゃないかなと思っています。
最初に何をするか
さて、この OSS に貢献するぞ!と決めたはいいものの「普段使っていてもバグなんて見つけてないしな...」という方も多いと思います。
そういった方におすすめなのは上で述べたように
- バグ報告に対して自分も再現したよ!というコメントをする
プログラミングをする上で避けて通れないのはバグで、いくらテストコードを書いていたとしてもバグをなくすことは現実的ではありません。
もちろんそれは OSS のプロダクトでも同じで、毎日たくさんのバグが報告され修正されています。
しかし、中には報告されたものの他の開発者の手元で再現しなかったり、特殊なケースでのみ発生するため優先度を落として対応しているものもあります。 そういったものに対して「自分の環境でも再現したよ!」とコメントすることでバグの原因がわかったり、優先度の見直しが行われ早急に対応が進むことがあり、バグが再現する環境を報告することには十分が意義があると考えています。
good first issue
Indicates a good issue for first-time contributors
初めて contribute するひと向けに、取り組みやすい issue などにこのラベルがつけられています。
大体そういった issue は description がしっかり書かれていたり、対応方針が明確になっていることが多い印象です。
また、よく分からなかった場合でも「この issue に取り組みたいんだけど、どうやって進めればいい?」のようなコメントをすると親切に答えてくれると思います。
注意すること
いくら OSS だからといって無闇矢鱈に PR を投げていいものではありません。
mentainer も暇ではなく限りある時間の中で PR をレビューするので、しっかりマージされる PR にするためには最低限のルールを守り reviewer の負担を下げる必要があります。
例えば以下のようなものです。
- PR の description を書く
「なぜこの PR が必要なのか」「この PR でなにを解決したのか」など書いておくと親切です。また、issue を紐付けておきましょう。 - テストを書く
変更内容だけ書いても本当に動くのか確認する必要があります。reviewer が手元でコードを動かして動作確認するのは負担になるため、なるべくテストコードを書き CI 上で動作確認できることが望ましいです。 どうしてもテストコードが書けない場合はその旨を description に書きましょう。 - コードのスタイルを整える
普段開発している code base とコードのスタイルが異なることは多々あります。最近は CI でコードスタイルをチェックしていたり、手元で format できる仕組みが整えられていることが多いです。
「郷に入れば郷に従え」と言うとおり指摘されたら素直に直しましょう。どうしてもそのスタイルに賛同できない場合は別の issue を立ててみてはいかがでしょうか? - PR のサイズはなるべく小さくする
OSS に限った話ではなく普段の開発を行う上でも重要ですが、気付いたら diff が大変なことになってしまうこともあると思います。
これも reviwer の負担を下げるために大事なことなので、diff が大きいなと思ったら PR を分けましょう。
いくつか基本的な注意事項を挙げましたがプロジェクトによって気をつけなければならないことは異なります。
contribution に関しては各プロジェクトでガイドラインを用意していることが多いです。
Deno の例を上げると公式ドキュメントやプロジェクトの README.md に contribution のガイドが載っているので、PR を立てる前は一通り目を通しておきましょう。
まとめ
自分が deno_std に PR を投げた体験をもとに、deno_std は初めて OSS 活動する人におすすめという話をしています。 また、OSS への貢献の種類と注意事項についても簡単に書いてみました*6。
この記事を読んで OSS 活動に興味を持ったり、活動のきっかけになると幸いです。
(おまけ) 自分が英文書くために使っているツール
自分はお世辞にも英語が得意だとは言えないです。
OSS 活動をする上で英語でのコミュニケーションは避けて通ることはできないと考えていて、OSS 活動への参加を躊躇う理由の一つでした。
しかし、最近の機械翻訳が非常に優秀なこともあり OSS 活動への心理的ハードルは大分取り除かれました。
そんなわけで普段どのようなツールを使って英文を書いているかメモしておきます。
- DeepL
DeepL Translate: The world's most accurate translator
みんな大好きなやつですね。英文書くときは大体これで再翻訳してみて意味が通じるかの確認に使うことが多いです。
自分が論文読むときに欲しかった... - Grammarly Grammarly: Free Online Writing Assistant 自分は本当に英作文に自信がないので課金しています。ニュアンス?ライティングのスタイル指定ができたり、改善理由の説明を表示してくれるので学ぶことが多いです。
- GitHub コミットメッセージの例文や issue の例文探したりと日々眺めています。