OSSコントリビューションはドキュメント修正から始めてみよう
はじめに
TL;DR
ドキュメント内の typo やリンク切れはチャンスです。GitHub 上でサクッとプルリクを作って出してみましょう。
概要と対象読者
本記事は OSS コントリビューションに関するポエム記事です。筆者はライブラリやアプリケーションのドキュメントで明らかな誤植を見つけたら修正プルリクを出すようにしているのですが、その方法や考えていることについて共有したく筆を執りました。
タイトルからもわかる通り、この記事は初心者向けです。OSS 活動にまだ一歩踏み出せていない学生/ジュニアエンジニア向けに書きました（筆者もジュニアエンジニアですが）。OSS ってなんだか難しそうだけど挑戦してみたいという方に「案外簡単なところからできるんですよ」ということが伝われば嬉しいです。
OSSコントリビューションって難しそう
一口に言っても様々
OSS へコントリビュートするのって難しそうな印象があります。かくいう筆者も大量のコントリビューションができているわけではありません。やはり他人が見ている他人のリポジトリへ何かを提案をするというのは一定のハードルがありますよね。そういう心理的なハードルに加えて、コントリビュート先のリポジトリが扱っている技術が高度である場合は、バグ修正や新機能実装が困難であることもあります。
やはり OSS 貢献は難しいから、筆者のようなジュニアエンジニアには無理なのでしょうか。答えは「いいえ」です。一口にコントリビューションといっても様々な形があるからです。例えば次に挙げるような行動は狭義/広義の OSS コントリビューションでしょう[1]。
- バグを issue で報告
- バグを見つけてコードを修正
- ドキュメントの誤植を修正
- OSS ライブラリのユーザグループとしてイベント主催・参加する
- StackOverflow や TeraTail でライブラリに関する質問に回答する
- SNS でそのライブラリの良さを宣伝したり、記事を書いたりする
OSS コントリビューションとは必ずしもコードを書いてコミットすることを意味するとは限りません。もしかしたら、すでに皆さんは OSS に多大な貢献をしているかもしれませんね。
ドキュメント修正をしてみませんか
ドキュメント修正も、OSS コントリビューションの 1 つの形です。みなさんは使っているライブラリやアプリケーションのドキュメントに誤植があった場合どうしますか。筆者もそうですが、誰かが修正してくれるだろうと考えて放置してしまいがちです。しかしドキュメントの誤植は OSS コントリビューションのチャンスなのです。いまでは多くのライブラリがドキュメントページを GitHub 上で管理しています。筆者が好きなライブラリだと Babylon.js や Vue.js などがそうです。それ以外にも Microsoft Docs や MDN Web Docs も GitHub で内容を管理していますね。
つまりこれらのドキュメントに誤植を見つけた場合、修正プルリクを送ることが可能なのです。
おススメの手順
ここでは参考に、筆者がドキュメントに誤植を見つけたときにプルリクを出すまでのステップをご紹介してみようと思います。
ソッコーでforkしてプルリク出す
もしそのドキュメントの誤植が明らかであれば、ソッコーでプルリクを出すのが肝だと考えています。時間をかけると「余計なお世話なのではないか」「変なことして怒られないかな......」など考えてしまうからです。ソッコーで出すために、筆者はなるべくリポジトリのクローンを行わないようにしています（後述）。
1. 同じプルリクが無いか確認する
まずは落ち着いて、自分が修正する内容と被るプルリクや issue が無いかを確認しましょう。誤植が既知であれば対応中の可能性もありますので、Open なプルリクのリストを検索します。
2. Forkする
コントリビュートするためにはリポジトリを Fork する必要があります。元のリポジトリの Fork ボタンを押して自分の Repogitories へ Fork しましょう。
3. Fork先で.キーを押してエディタを起動
GitHub の場合は自動で Fork 先のリポジトリが開くはずです。そしたらそのまま「.」を押し、ブラウザ上でエディタを開きます。
4. ブランチを作成＆チェックアウト
Fork 直後の場合はデフォルトブランチにいるはずなので、適当な名前のブランチを作成してチェックアウトします。ブラウザ上のエディタであれば UI 上で行えます。
5. 対象のファイルを修正してコミット
あとはエディタ上で対象のドキュメントファイルを修正します。多くの場合はマークダウンファイルですので、右のペインにプレビューを出しながら編集することになるでしょう。
修正が終わったら修正内容をコミットします。コミットメッセージには変更内容がわかりやすいような文言を採用しましょう。また、この方法ですとコミットした時点で自分の Fork リポジトリへ内容が Push されます。
6. プルリクを作る
コミットした状態で自分の Fork リポジトリのページに行くと、プルリクを作るボタンが出ているので、そこからプルリクを作成して Submit します。
これでドキュメント修正提案は完了です。あとはコミュニケーションの必要があれば対応し、マージされるのを待ちます。
補足
ガイドラインに従おう
今回、プルリクの本文やタイトルについては触れませんでした。これについてはリポジトリによって温度感が違ってくるので、特に初めてのリポジトリでは必ずガイドラインを確認してください。バグ修正であれば、プルリクを作る前に issue があることが多かったり、マナーだったりすることがありますが、明らかで軽微なドキュメント修正であれば issue を立てる前にプルリクを出しても大丈夫なケースが多いです。それを加味して今回は「ソッコーでプルリクを送る」ことを達成するためにこのフローを紹介しました。
他のプルリクを参考にしよう
ガイドラインの話にもかぶりますが、リポジトリの温度感を知るために他のプルリクを観察することも良いでしょう。そもそもガイドラインが無いリポジトリやガイドラインがゆるいリポジトリもあるのですが、例えばプルリクのタイトルにプレフィックスをつける文化があるかもしれません。
気負わず行こう
プルリクを出すときは多少なりとも緊張するものです。赤の他人の作ったものに口を出すことになりますし、相手がすごい怖い人だったらどうしよう、なんて考えてしまえばプルリクを送るに送れませんよね。加えて言語の壁が立ちふさがる場合も往々にしてあります。そういう状況下で「気負わず」というのはなかなか難しいかもしれません。
しかしライブラリ開発者にしてみれば、見ず知らずの（海外の）人がドキュメントの細かい誤植を見つけて報告するのみならず直してくれたということになりますし、このことについて怒る人はそうそういないでしょう（少なくとも筆者は怒られたことがありません w）。むしろ Thank you!といってすぐマージしてくれるのではないでしょうか。
修正内容が軽微であれば、無理に細かく説明する必要はありませんので、簡単な英語で一言、「typo がありましたよ」と言ってあげれば大丈夫です。あまり気負わずにいきましょう。
おわりに
まとめ
本記事では、OSS コントリビューションへの最初の一歩の参考としてドキュメント修正を提案すしました。ドキュメント修正も立派なコントリビューションであることを説明したうえで、筆者がおすすめするプルリク作成フローを紹介しました。
OSS 活動は強いエンジニアの専売特許ではありません。むしろ様々なスキルレベルのエンジニアが行うことでリポジトリやコミュニティが成長していきます。この機会にぜひ、OSS コントリビューションを始めてみてはいかがでしょうか。
そしてもちろんこの記事の GitHub も公開していますので、もし誤植等あればコミット大歓迎です。
参考文献
Discussion