結城です。
OSSプロジェクトへのコントリビュートの「べからず集」記事について、まだ要領を掴めていない人が「自分のしようとしていることもそれにあてはまるのではないか？」と心配になってコントリビュートをためらうことがないように、具体的な例と考え方を紹介するシリーズの3本目です。前回（2回目）に続き、今回は3つ目の「べからず」として挙げられている、いきなり作業を始めるべきではないという話について説明します。
3. 了承なしに作業を始めない（コンセンサスを得てから開発に着手する）
この記事をご覧になっている皆さんの中には、「実際にコードを書いて、早くOSS開発に参加したい」という思いが強い人もいるでしょう。また、「英語の読み書きは苦手だけれどもコードなら書ける」ということで、端的にコードの提供だけで済ませたい人もいると思います。筆者もかつてはそのように考えていて、言葉での説明を煩わしく感じていました。
ですが、確実に「これは説明も了承もいらない」と言いきれるごく限定的な状況以外では、説明や了承を端折るのはいろいろな意味でハイリスクです。ともすれば、開発に協力したいと思ったプロジェクトの運営に無用な負担をかけることにもなりかねません。そのようなデメリットを伴わず、着実に手堅く開発に参加する方法は、結局は「急がば回れ」ということになります。
業務においてチームで共同作業するときは、すでによほど充分な信頼関係を築き上げられている場合を除いて、チームメンバー間で密にコミュニケーションを取るのが基本です。事前のすり合わせなしに規模の大きな変更を突然見せつけられても、他のチームメンバーはその内容を理解するのに苦労を要しますし、その内容がチームの期待に反していてチームの成果物には取り込めないと判断されてしまうと、その分のすでに行われてしまった作業は無駄になってしまうからです。「了承なしに作業をして、その結果のプルリクエストをいきなり送りつける」というのは、それと同じことなのです。
先にイシューを立てて、こちらの意図をきちんと説明しよう
たとえ1行だけの変更であっても、何の説明もないプルリクエストだけが単発で送られてきては、開発者は戸惑うだけです。
「開発者なんだからプロジェクトの隅々まで完璧に把握してるはずだろう、だったら説明なんかなくてもコードを見れば分かるはずだ」と思いますか？
残念ながら、それは過剰な期待というものです。開発者といえど、ある程度以上の複雑さを持ったソフトウェアでは、どの変更がどこにどういう影響を与えるのかを一目で判断するのは難しいです。変更が予想外の場所で不具合を引き起こす「後退バグ」が起こったり、後退バグの早期検出を図る「回帰テスト」があったりするのは、そのためです。
開発者がプルリクエストの内容をスムーズに理解し、レビューやマージするかどうかの判断を迅速に行えるようにするためには、そのプルリクエストがどんな問題を解決する物なのかの説明が必要です。具体的には、「修正したい現象の再現手順」「現時点で実際に得られる結果」「その変更によって得られるようになる、本来期待される結果」の説明が必要です。
これは、イシューで問題を報告するときの内容と変わりません。ということは、すでにイシューが立てられている問題なのであれば、そのイシューの番号やURLを添えて、「これを修正するための変更です」と書くだけで十分1ということでもあります。プルリクエストを既存イシューと関連付ければ、経緯や過去の議論をたどりやすくなるメリットも得られます。
そのようなイシューが存在しているのであれば、「私はこの問題の解決に取り組もうと思う」と宣言のコメントを書いて、進捗状況を随時共有しながら作業に取りかかるのがよいです。そうすると、もしプロジェクトオーナーや他の協力者がすでに何か作業の見通しを立てているのであれば、「ちょっと待って欲しい」などのコメントが付くかもしれません。せっかく何かできるチャンスだったかもしれないのに出鼻をくじかれるのは残念ですが、作業が徒労に終わってしまうのを防げたと考えて、別の有意義な作業に取り組むべく頭を切り替えましょう。
なお、そのようにイシューを探す過程で、OSSプロジェクトのイシュートラッカーで「Good First Issue」や「Good First Bug」などとタグ付けされたイシューを見かけることがあるかもしれません。規模の大きなプロジェクトで、プロジェクトに協力してくれる人を随時募っている場合には、新規のプロジェクト参加者が挑戦するのにちょうどいい難易度の課題に、そのようなタグが付けられている場合があります。特に自分自身では何もつまずいていないものの、自分が普段からお世話になっている有名なOSSの開発に参加してみたい、問題解決に取り組んだりプルリクエストを出したりしてみたいという人や、あるいは、自分がつまずいた問題が大きすぎて手に負えないので練習をしたいという人は、そういったイシューの解決に取り組んでみるとよいでしょう。分からないことがあったら、質問をするとプロジェクトに参加中の先達からアドバイスをもらえるかもしれません。
まだ誰も報告していない問題であれば、まずはイシューとして報告します。英語が苦手だからイシューを立てるのは怖い、だからプルリクエストだけで済ませたい、という気持ちは分かりますが、それではかえって開発者に負担をかけてしまったり、悪ければ開発者に無視されてしまったりもします。報告に書く内容のまとめ方や英語で説明するときの考え方を参考にしながら、ぜひイシューを立てることに取り組んでみてください。
プルリクエストから始めてもいい場合
プルリクエストはイシューと紐付けるのが原則だと述べたところですが、動作そのものに影響がなく、是非の議論の余地が無い変更の場合、イシューを経ずにプルリクエストから始めても問題無いことがあります。たとえば以下のようなケースです。
-
ローカルな変数名やプライベートな関数名の綴り間違いの修正
-
言語リソースの誤訳の修正
-
言語リソースの未翻訳部分に対する訳文の追加
-
Webサイトやドキュメントの誤記の修正
-
Webサイトやドキュメントのリンク切れの修正
こういうものは「再現手順」「実際に得られた結果」「期待される結果」の枠に当てはめにくいので、イシューを立てようと思うと逆に難しいです。実際のプロダクトやドキュメントに残る形でフィードバックをしたいという思いが強い場合には、こういったものから手を着けてみるのもよいかもしれません。
GitHubでは、ログイン済みの状態でファイルの個別のページを表示すると、オンラインで編集を開始できます。他人のリポジトリだった場合、変更を保存するタイミングで自動的に自分のアカウント配下にフォークが作られて、プルリクエストの作成画面になります。GitLabやBitBucketなどのサービスでも、操作の順番は多少異なりますが、同様のことができます。
ただ、この方法での変更結果はコミット前に「テストする」ということが難しいです。そのため、変更時に意図せず文法エラーが混入してしまうこともあり、その変更をマージすると、初期化に失敗して起動できなくなってしまったり、ドキュメントのレイアウトが崩れてしまったり、というようなこともあり得ます。
実際に、筆者が公開しているFirefox用アドオンにおいても、日本語と英語以外の翻訳リソースを提供してもらえることがありますが、文法エラーが残ったままの変更をマージしてしまって、自分の手元の環境で突然動かなくなって焦った、ということが度々ありました2。Webサイト上からのファイル編集でプルリクエストした場合などには、事後的にでもよいので、どんな変更であっても、必ず一度は自分の手元で動かして（表示して）みて、問題が無いかどうかを確認するようにしましょう。
また、変数名・関数名・API名といった、動作に影響を与える部分の誤記の修正は、特に慎重に行う必要があります。
ローカル変数やプライベートなメソッド・関数は、他から参照されないため、変更しても動作が壊れることはあまりありません。しかし、グローバルな変数や公開のメソッド、モジュール名自体の誤記は、下手に変更すると動作を壊してしまうことがあります。
また、一見するとプライベートな変数や関数であっても、コード片単位でのインクルードや、メタプログラミングによって実行時に外部から参照されるなどのことによって、変更が思わぬ所に影響を及ぼしてしまうリスクがあります。
以上のような事情を踏まえ、実行可能なコードに関わる変更は、原則として、GitHubなどのサイト上から編集して直接プルリクエストするやり方を取らずに、手元で動作に問題が無いことを確認してからプルリクエストを出すようにすることを、強くお勧めします。
なお、プロジェクトメンバー間での対面での相談やチャットなど別の場所ですでに議論が尽くされていて、後はコードを変更するだけであった場合に、傍目からは「急にプルリクエストが行われて、何故かすぐにマージされた」という見え方になる場合もあります。
これは経緯を知らない人には区別が付かないので、注意が必要です。「あっちはすぐにマージしてるのに、なんでこっちは放ったらかしにされるんだ！」と思うようなケースに遭遇した場合でも、「ならば自分も」と短絡的には考えないようにしましょう
まとめ
以上、「了承なしに作業を始めない（コンセンサスを得てから開発に着手する）」という原則について、実例を挙げて解説してみました。
この解説は、OSSへのコントリビューションを増やすことを意図した取り組みであるOSS Gateで開催しているワークショップの中で得られた知見をまとめた本、「これでできる！ はじめてのOSSフィードバックガイド」の一部を抜粋・再編集した物です。本編ではこのほかにも、問題の報告の仕方やありがちなミス、フィードバック初心者の方が戸惑いがちな点について、なるべく具体例を示しながら、幅広く解説してみています。リンク先では原稿の全文を公開していますが、手元に置いて参照しやすい形式での販売も行っていますので、読書スタイルに合った形式で参照して頂ければ幸いです。
OSS Gateでは、新型コロナウィルスの感染拡大防止の観点から、現在は東京地域を主体としたワークショップをオンライン（Discord）で開催しています。次回開催予定は12月12日（土曜）13:00からで、ビギナー（ワークショップで初めてのフィードバックを体験してみたい人）・サポーター（ビギナーにアドバイスする人）のどちらも参加者を募集中です。ご都合の付く方はぜひエントリーしてみて下さい。業務のチームのメンバーや後輩の方にOSSへのコントリビュートをしてもらいたいと思っている方は、自身をサポーターとして、メンバーや後輩の方をビギナーとして参加のお声がけをして頂くのもおすすめです。
また、当社では企業内での研修としてのOSS Gateワークショップの開催も承っています（例：アカツキさまでの事例）。会社としてOSSへの関わりを増やしていきたいとお考えの企業のご担当者さまは、お問い合わせフォームからご連絡頂けましたら幸いです。
