OSSコントリビューションその2 ドキュメント修正のイシューを探す

February 16, 2018twitter:RichardImaokaJP

こんにちはみなさん、リチャードです。

前回 OSSコントリビューション　イシューの見つけ方　その1 という記事でOSSコントリビューションを始めたい方向けに取り組むべきイシューの探し方を紹介しました。

しかし、ある程度規模の大きなOSSになってくると、上の記事で紹介した探し方で100を超えるような数のイシューがみつかってしまい、どれから手を付けていいのかわからない…という場合もよくあります。そんなときにドキュメント修正のイシューから始めてみては？という提案です。

TL;DR

ドキュメント修正のイシューは比較的手を付けやすいものが多い
ドキュメント修正のイシューでもちゃんと知識は身につく
普段ドキュメントを修正しつつ、できそうなコードの変更があればそれをやればいい

それではいってみましょう。

ドキュメント修正のイシューは比較的手を付けやすいものが多い

私はakkaというOSSに2年ほど貢献しています。自分があげたPull Requestはこの記事を書いている時点92、マ－ジされたものは86でそのうちドキュメント修正のイシューが70あります。

70 / 86 = 81%

つまり私の過去のakkaに対する貢献は8割以上ドキュメントの修正です。

「なんじゃこいつ、コードじゃなくてドキュメントばっかりやってる素人じゃねえか」と思う方もいるでしょうが、まさにその通りです。そんな私でも90近いコミット数を稼ぐことができました。僕自身はコミット数自体を伸ばしたいと思っていて、それを点数を稼ぐゲームのように捉えているので、ドキュメントであれ何であれ簡単なイシューでコミット数を稼げるのはありがたいことです。

そうやってせっせとドキュメントの修正をしていたら、なんと2017年6月、akka 2.5.3のリリース時に紹介してもらいました。

実はこの2.5.3リリースの前にボーナスチャンスがあって、簡単なドキュメント修正を大量のファイルに対して行うことで30コミット近く稼ぐことができました。

https://github.com/akka/akka/issues/23052

簡単な作業しかしてないのですが、それでもこうやって言及してもらえると嬉しいものです。

ドキュメント修正のイシューでもちゃんと知識は身につく

ドキュメント修正のイシューをこなしていても、ちゃんと対象のOSSに対する知識は身についていきます。ドキュメントの修正とはいえ、当該範囲の知識なしにできる物は少ないのです。

よくあるイシューとして「新機能を足した、しかしドキュメントが更新されてない、新機能の説明を足すべき」「このドキュメントのこの部分が実際のコードの動作と違う、修正すべき」といった例があります。どちらも「新機能自体を理解する」「実際のコードの動作を検証する」という作業をしないと正しくドキュメントを書くことができないことはわかると思います。

私が取り組んだ実際のPull Requestだとこれがよい例ですね。サンプルコードを追加しましょうというイシューでしたが、サンプルコードを書いて走らせて、動作確認して、と何度か繰り返した後Pull Requestをあげることができました。サンプルコードが思った通りの動作をしてくれなくて試行錯誤した記憶があります。それが逆にakkaの内部を理解することにつながりました。

https://github.com/akka/akka/pull/23761

次のこのPull Requestは別の場所(akka-http)にあったドキュメントの一部をほぼコピーだけするような作業で終わるはずだったイシューでしたが、最終的には文章に多少のアレンジを加える必要がありましたし、もちろんサンプルコードの動作確認もおこないました。おかげでakkaのthread周りについて詳しくなるきっかけを掴むことができました。

https://github.com/akka/akka/pull/22998

つまり、ドキュメントの修正であっても自分でコードを書いて対象のOSSを動かす作業が必要な場合が多いので、続けていけば知識を身につけることができます。

普段ドキュメントを修正しつつ、できそうなコードの変更があればそれをやればいい

そして、ドキュメントの修正をやるからといって、それだけをやる必要はないわけです。コードの変更も、どちらもやればいいのです。

ドキュメント修正のイシューの方が簡単なことが多いので、普段そちらをやってOSSコントリビューションのペースを保ちつつ、時間がたくさん取れるときや自分が得意そうな範囲のコードの変更があればそれも行いましょう。たとえ「メソッドにパラメタを一つ足す」「細かいバクの対応」といったレベルでも、自分のコードの変更がOSSに取り込まれると嬉しいものです。

OSSコントリビュートしたい方には朗報！

さて、最後に宣伝ですが、私もScalaMatsuri 2018スタッフとしてお手伝いしている以下のイベントがあります。 OSSコントリビュータとしてロケットスタートを切るには絶好の機会です。akka、twitter4s、sbt、aeron、ScalikeJDBCという有名OSSからメインの凄腕メンテナさん達が参加・指導してくれます。協力してくれるメンテナさんたちは「メンテナチームの一員」といったレベルではなく、それぞれのOSSプロダクトの創始者もしくはここ数年でコミット数1、2位の、本当に各プロダクトを代表するメンテナさんたちです。

さあ、あなたもOSS貢献の一歩を踏み出してみませんか？

https://jsa.connpass.com/event/78748/

それから例によって、僕に何かお手伝いできることがあればtwitterでなんでも聞いてください。Scala関連のOSSについて、OSS貢献したいけど英語で困っている、もうちょっと細かいイシューの探し方について聞きたい、akkaに関すること、できないことはできませんが、できることならみなさんのOSS活動をお手伝いしますよ。