結城です。
ノータブルコードに便乗して、実際のOSSのフィードバックを見て「ノータブルフィードバック」と題してお届けする記事の3つ目は、当社の足永さんがcollectdというソフトウェアに対して行った、リリースマネジメントに関するフィードバックです。
実際の報告
■タイトル The source packages of collectd-5.9.2 aren't generated by the formal procedure ≪タイトル：colelctd-5.9.2のソースパッケージが通常の手順で生成されない≫ ■説明 Version of collectd: collectd-5.9.2 on git ≪collectdのバージョン：git上のcollectd-5.9.2≫ Expected behavior≪期待される結果≫: version-gen.sh script should generate "5.9.2" on collectd-5.9.2 tag. ≪version-gen.shスクリプトがcolelctd-5.9.2タグに基づいて「5.9.2」を生成する。≫ Actual behavior≪実際の結果≫: version-gen.sh script generates "5.9.1.7.gdfb9dd0 on collectd-5.9.2 tag. ≪version-gen.shスクリプトがcolelctd-5.9.2タグに基づいて「5.9.1.7.gdfb9dd0」を生成する。≫ Steps to reproduce≪再現手順≫: $ git clone https://github.com/collectd/collectd.git $ cd collectd $ git checkout collectd-5.9.2 $ ./version-gen.sh Cause of the issue≪問題の原因≫: collectd-5.9.2 tag isn't annotated. ≪collectd-5.9.2タグに注記が付いていない。≫
フィードバックの経緯
足永さんがとある案件でcollectdの独自改修版を作成して、お客さん向けに提供するためのパッケージを所定の手順で作成しようとしたところ、当時の最新リリース版である「5.9.2」からの派生版なので「5.9.2.（リビジョン番号）」というバージョン番号が自動生成されるはずが、なぜか「5.9.1.（リビジョン番号）」というバージョン番号になってしまう、という現象に遭遇しました。
この原因を足永さんが調べたところ、以下のことが分かりました。
-
パッケージ作成用のスクリプトは、Gitリポジトリに対して打たれたタグのメッセージが特定の形式に則って書かれている場合にのみ、それを正常なバージョンとして認識するようになっている。
-
バージョン5.9.2のタグのメッセージは、その形式に則っていなかった。
実際に、公開されているcollectdに対して何も変更を行っていない状態でパッケージを作成しようとしても、やはり同様の現象が発生する状態でした。そのため、足永さんはこの問題をcollectdプロジェクトで解決されるべき物として、調査結果を踏まえてフィードバックしました。
報告の後のコメントのやり取りの中では、collectdプロジェクトにおいてリリース作業の担当者が今回から変わっていたことと、前任者から手順が正しく引き継がれていなかったためにタグのメッセージが適切に設定されていない状態だったということが分かりました。その後、問題の状態は解消され、この報告もクローズされています。
注目したい点
「作成されたパッケージのバージョン番号が違っている」というつまずきに遭遇したときには、暫定的な回避として「できたファイルのバージョン番号の部分をとりあえず書き換えて済ませる」というような対策を取ることが多いでしょう。そういったその場しのぎだけで終わらせずに開発元にフィードバックすると、同じ問題につまずく人が減ります。
この報告には、問題報告の基本の3要素である「再現手順」「期待される結果」「実際の結果」が揃っていて、再現手順には実際に操作したコマンド列もそのまま記載されています。文章で長々と説明しなくても、要点を押さえてあれば適切に伝わるということがよく分かります。
「期待される結果」「実際の結果」の説明文の英語の表現にも着目してください。
version-gen.sh script should generate "5.9.2" on collectd-5.9.2 tag.
「パッケージ作成手順に従って作業したら5.9.2というバージョンが付くべき」ということを言い表すのに、リポジトリに含まれているパッケージ作成用のスクリプトを主語にして「このスクリプトはこのような事をするべき」という書き方をしています。日本語で言いたいことを余すことなくすべて英語で言い表そうとしなくても、無生物を動作の主体として明記することで簡潔に表現できるという好例でしょう。
このフィードバックの面白いところは、ソフトウェアそのものの不具合というよりも、プロジェクトのリリースマネジメントへのフィードバックとなっているという点です。プロジェクトにおいて作業を複数人で分担している場合に、そのときの作業者の属人的な知識に依存したまま体制が組まれてしまっていると、他の人に作業が引き継がれた後にこのような形でトラブルが起こる場合があります。このフィードバックがなされていなければ、新しい担当者は次のリリースで同様の問題に遭遇し、原因の究明に奔走する羽目になっていたかもしれません。
まとめ
ノータブルフィードバックの3回目として、コードでもドキュメントでもない部分へのフィードバック例をご紹介しました。
このような「身近なところで遭遇したつまずきをOSS開発プロジェクトにフィードバックする」ということをテーマに、まだOSSにフィードバックをしたことがない人の背中を押す解説書 「これでできる！ はじめてのOSSフィードバックガイド ～ #駆け出しエンジニアと繋がりたい と言ってた私が野生のつよいエンジニアとつながるのに必要だったこと～」を、2月29日に電子書籍としてリリースします。本記事の内容はこの本からの抜粋となっています。ダウンロード購入のチャンネル、紙媒体版などの詳細については、は前々回記事を併せてご参照下さい。
書評のご紹介
前回記事に続き、筆者が個人的にご縁のあった関係で、イラストレーター業とWebデザイナー業を並行しておられるえす吉さんより書評を頂きましたのでご紹介します。ありがとうございます！
全体を通して豊富な実例とあわせた解説がされていて、最後まで詰まることなく読み進められました！ 初心者が不安に感じる箇所を章ごとに丁寧に解消してくれるので、読み終わる頃には、この本を片手にまずは身近な問題に一歩踏み出してみよう、と思える内容だと感じました。
実際にそのOSSを切実に必要としている人からのフィードバックは、OSSの使い勝手やドキュメントの質の向上のために非常に重要です。また、Webサイトの「アプリ化」がめざましい昨今では、Web制作とOSSの関係性はより密になってきています。えす吉さんのようにWeb制作の現場でOSSをユーザーとして利用される立場の方からもOSSへフィードバックすることのハードルが下がって、仕事環境や成果物が改善されていくことに繋がれば何よりです。
