OSSのソースコードを読み解く、またはOSSにコントリビュートするコツを、Mitchell Hashimoto氏に学びます。

• はじめに
• OSSのソースコードを読み解くコツ
  • ステップ１：ユーザーになる
  • ステップ２：ビルドする
  • ステップ３：内部構造を理解する
  • ステップ４：最近のコミットを読む・再実装する
  • ステップ５：小さな変更を加える
• おわりに
• 参考

はじめに

TerraformやHashiCorpで有名なMitchell Hashimoto氏によるこのブログ記事を読みました：

• Contributing to Complex Projects – Mitchell Hashimoto

複雑なOSSのコードベースを理解しコントリビュートに繋げるまでの流れが、分かりやすくまとめられています。

今回は日本語でこの記事の要点をメモし、備忘録として残します。気になる方はぜひ原文もご覧ください。

OSSのソースコードを読み解くコツ

ステップ１：ユーザーになる

第一歩目は、実際にそのプロジェクトを使うユーザーになることです。

プロジェクトを知っていることやドキュメントを読んでいることと、ユーザーとして実際にプロジェクトを使っていることの間には大きなギャップがあります。そのプロジェクトを使って、動く小さなものを作ってみましょう。

また、この段階でコミュニティに参加することも有効です。Discordやミートアップに参加したり、コミュニティの登壇を試聴したりすることで、プロジェクトのエコシステムや慣習を学ぶことができます。

ステップ２：ビルドする

次は、プロジェクトをビルドし動作するバイナリを作成できるようになりましょう。

ビルドシステムを理解する必要も、依存関係を把握する必要もありません。ただガイドに従い、自身にとって十分動作するバイナリを作成すればよいのです。

ビルド方法を把握する前に、コードを読まないようにしましょう。プロジェクトを理解するには、自分でプロジェクトを変更し実験を繰り返すことが大切です。ビルドすることができなければ、自分で実験することはできません。

また、このタイミングでテストを実行する方法を把握しましょう。自分でプロジェクトを変更し実験を繰り返すときに、テストの実行が役に立ちます。

ステップ３：内部構造を理解する

“Trace down, learn up” アプローチで、プロジェクトの内部構造を学びます。

・Trace down

Trace downでは、機能やユースケースから始めて、内部へ深くコードの流れを追跡します。

このタイミングでは、その動作原理を理解する必要はありません。ただただ、ファイルや関数を"追跡"していくだけで十分です。ノートにメモを取りながらやっても良いでしょう。

また、プロジェクト全体を一気に理解しようとしてはいけません。ユーザーとして馴染みのある、シンプルな機能をピックアップして追跡していきましょう。

・Learn up

Trace downで外側から内部に向かってコードを追跡したら、今度は逆に、最も抽象度の低い内側から外側に向けて、どのようにコードが機能しているのかを理解していきます。

これら“Trace down, learn up”を繰り返すことで、システムの理解を深めていきます。

またこのプロセスの中で、実際にコードを変更したり、壊してみたりして実験することも有効です。ログを追加したり、ちょっとした機能を追加したり、既存の機能を少し変更したりしてビルド&実行し、何が起きるのかを確かめます。こうした実験を経て、システムがどう機能しているのかの理解を深めるのです。

ステップ４：最近のコミットを読む・再実装する

内部構造を学ぶ最終段階として、最近のコミットを読み、その変更理由を理解できるか確かめます。

プロジェクト全体や学習中の特定ファイルのコミット履歴を確認し、変更内容を読んで自分の理解と照らし合わせるのです。

また、対象のコミット直前の状態にリポジトリを戻し、バグを再現して自分でコードを変更し、解決を試みるのも有効です。メンテナーやコントリビューターの実際の修正内容と比較し、より理解を深めることができます。

ちょうど教科書の練習問題を解くような感覚です。

ステップ５：小さな変更を加える

小さな変更から始め、徐々に大きな課題に取り組むようにします。ここまでの段階でプロジェクトの技術的側面は理解しているため、次はコントリビューションやレビューのプロセスを学ぶことが目的です。

難しいのは、ちょうど良い小さな課題を見つけることです。これには銀の弾丸はありません。

まずIssuesを眺めて、初心者向けのものを探します。最初に手を付けたものがうまくいかず、別の課題に移ることもよくあることです。多くのプロジェクトでは、新規のコントリビューターのための"contributor friendly"ラベルが付けられていることがあるので、参考にしましょう。

また、コントリビュートプロセスがドキュメント化されている場合は、それに正確に従いましょう。

おわりに

以上、Mitchell Hashimoto氏のブログ記事からOSSのソースコードを読み解くコツのポイントをまとめました。

個人的には、

• Trace down, learn up
• まずビルド方法を知る

辺りは特に参考になりました。

どなたかの参考になれば幸いです。

Follow @bioerrorlog

[関連記事]

www.bioerrorlog.work

参考

• Contributing to Complex Projects – Mitchell Hashimoto