結城です。

ノータブルコードに便乗して、実際のOSSのフィードバックを見て「ノータブルフィードバック」と題してお届けする記事の5つ目は、当社の畑ケさん*1がmeta-clangというプロジェクトに対して行ったフィードバックです。

実際の報告

■タイトル

meta-clang's llvm-config is not compatible with MULTILIBS
≪meta-clangのllvm-configが、MULTILIBSと互換性がない≫

■説明

≪不具合の説明≫
One of the our target boards(RZ/G2E)'s Yocto default conf/local.conf specifies MULTILIBS = "multilib:lib32" and DEFAULTTUNE_virtclass -multilib-lib32 = "armv7vethf-neon" to be able to run 32bit ARMv7 binaries.
≪私達が開発している対象のボード（RZ/G2E）の一つのYoctoレシピの既定のconf/local.confには、32bit ARMv7バイナリを動かすために、「MULTILIBS = "multilib:lib32"」と「DEFAULTTUNE_virtclass-multilib-lib32 = "armv7vethf-neon"」という設定が含まれています。≫
So, built binaries will be installed in /usr/lib64/ instead of /usr/lib.
≪そのため、ビルドされたバイナリは/usr/libではなく/usr/lib64/の中にインストールされます。≫

Because our SDK environment does not assume /usr/lib for library installation directory.
≪なぜなら、私達のSDKの環境は/usr/libをライブラリのインストール先ディレクトリーとして想定していません。≫
Instead, /usr/lib64 is used for 64bit libraries and shared object. And /usr/lib32 is used for 32bit objects.
≪その代わりに、/usr/lib64は64bitライブラリと共有オブジェクトに使われます。また、/usr/lib32は32bit版オブジェクトに使われます。≫

ref: https://llvm.org/docs/CMake.html#frequently-used-cmake-variables

To Reproduce
≪再現するには≫

Steps to reproduce the behavior:
≪この動作を再現するための手順：≫

Specify MULTILIBS = "multilib:lib32" and DEFAULTTUNE_virtclass-multilib-lib32 = "armv7vethf-neon" in local.conf
≪「MULTILIBS = "multilib:lib32"」と「DEFAULTTUNE_virtclass-multilib-lib32 = "armv7vethf-neon"」をlocal.confの中で設定する≫

Add meta-clang layer
≪meta-clangレイヤを追加する≫

bitbake clang-cross-aarch64
≪bitbake clang-cross-aarch64を実行する≫

add meta-browser and meta-rust layer
≪meta-browserとmeta-rustのレイヤを追加する≫

bitbake firefox
≪bitbake firefoxを実行する≫

See error
≪エラーが表示される≫

Error
≪エラー≫

≪実際に出力されたエラーの全文が貼り付けられているが、ここでは省略。≫

Expected behavior
≪期待される挙動≫

meta-clang's llvm-config can work with DEFAULTTUNE_virtclass-multilib-lib32 specified environment.
≪meta-clangのllvm-configが、「DEFAULTTUNE_virtclass-multilib-lib32」が指定された環境で動作すること。≫

llvm-config points to ${RECIPE_SYSROOT}/usr/lib/clang/8.0.1/lib/linux/ but actual libclang libraries are put in ${RECIPE_SYSROOT}/usr/lib64/clang/8.0.1/lib/linux/
≪llvm-configは「${RECIPE_SYSROOT}/usr/lib/clang/8.0.1/lib/linux/」を指定しますが、実際のlibclangライブラリは「${RECIPE_SYSROOT}/usr/lib64/clang/8.0.1/lib/linux/」に置かれます。≫

LLVM insists that using LLVM_LIBDIR_SUFFIX to control installation directory suffix such as lib64 or lib32.
≪LLVMでは、インストール先ディレクトリーの末尾をlib64やlib32のように変えたい場合、LLVM_LIBDIR_SUFFIXを使う必要があります。≫

We should handle library directory glitch it llvm-config with LLVM_LIBDIR_SUFFIX.
≪私達はLLVM_LIBDIR_SUFFIXを伴ったllvm-configのライブラリーの配置先ディレクトリーのずれに対処するべきでしょう。≫

Desktop (please complete the following information):
≪ビルド環境のデスクトップ機（以下の情報を埋めてください）≫

OS: Ubuntu

Version 16.04.6 LTS

Additional context
≪追加の情報≫

(Updated) I'd encountered this issue during meta-browser's firefox recipe building.
≪（追記）私はこの問題に、meta-browserのFirefoxのレシピを使ってのビルド作業中に遭遇しました。≫

フィードバックの経緯

組み込み機器向けにカスタマイズしたLinuxディストリビューションを作成するためのツールセットの一種であるYoctoでは、そのLinuxディストリビューションに組み込めるパッケージが多数公開されています。その中で、C言語のコンパイラであるclangを組み込むための設定ファイルやスクリプトを提供しているのが、meta-clangというプロジェクトです。畑ケさんがとある組み込みボード*2用にFirefoxをビルドしようとして、Firefoxのビルドに必要なmeta-clangを構成に入れたところ、ビルド結果が想定通りにならず、Firefoxパッケージをビルドできないという状況に遭遇しました。

この時点で原因がmeta-clangにあるということは明らかだったため、畑ケさんは手元でとりあえずの回避策を講じた上で、問題に遭遇したということをmeta-clangにフィードバックしました。すると、その報告に対してプロジェクトオーナーから「Can you cook up a patch?（パッチを作ってもらえませんか？）」とコメントが返ってきました。そこで、畑ケさんは「I'm cooking up patches....（今パッチを作成中です……）」とコメントした上で、手元で行っていた暫定的な回避策を一般公開できるようにより洗練させ、プルリクエストにしました。

その後パッチがマージされたことで、この報告もクローズされています。

注目したい点

これも、「自分の手元でなんとかして動くようにした」というところで終わらせないで、開発元にエスカレーションした事例です。

最終的にプルリクエストを出すところにまで至っていますが、畑ケさんは当初はそこまでするつもりはありませんでした。しかし 「パッチを作ってもらえませんか？」と逆に依頼された ことがきっかけとなり、プルリクエストの作成に至りました。フィードバックは「自分にできることをまずはやる」所から始めるとよいですが、やろうと思っていなかったことに挑戦する機会にもなるということの好例と言えるでしょう。

この報告はプロジェクトのイシューテンプレートに基づいて書かれていていますが、「To Reproduce」には再現手順と実際の結果が、「Expected behavior」には期待される結果が書かれており、問題の報告の基本の3要素がきちんと含まれていることが分かります。

フィードバックする前の予備調査の時点で、畑ケさんはこの作者の人が、ここで使おうとしている「MULTILIBS」という機能を使っていないようだ、ということを把握していました。そのため、再現手順や環境の作り方をより細かく具体的に書き、作者が容易に現象を確認できるようにすることを意識したそうです。CJKの言語に特有の事情を詳しく説明した前回の例と、考え方は同じです。

文中に登場している「glitch」という単語は、辞書では「故障」「誤動作」「異常」といった意味と出ますが、語源は「slip（滑る）」や「slide（ずらす）」と同じで、ニュアンスとしては「本来の正常な状態からずれてしまっている」状態を表すそうです。インデントのずれや画像の位置ずれなどにも使える表現ということで、覚えておくとよいでしょう。

ところで、この例も報告文の中にミスタイプがあります。

We should handle library directory glitch it llvm-config with LLVM_LIBDIR_SUFFIX.

この文の「it」は誤記で、「in」が正しいです。先の筆者の例と併せて見ると、誤記はありふれたものだということをなんとなく感じて頂けるのではないでしょうか*3。

まとめ

ノータブルフィードバックの5回目として、開発者が想定していない使い方での不具合を報告するフィードバック例をご紹介しました。

このような「身近なところで遭遇したつまずきをOSS開発プロジェクトにフィードバックする」ということをテーマに、まだOSSにフィードバックをしたことがない人の背中を押す解説書「これでできる！はじめてのOSSフィードバックガイド～ #駆け出しエンジニアと繋がりたいと言ってた私が野生のつよいエンジニアとつながるのに必要だったこと～」を、電子書籍としてリリースしました。本記事の内容はこの本からの抜粋となっています。ダウンロード購入のチャンネル、紙媒体版などの詳細については、「ノータブルフィードバック」第4回目の記事を併せてご参照下さい。

*1 「はたけ」と読む珍しい名字のため、社内でもよく「ケ」が行方不明になりがちです。

*2 複合機やカーナビなどの制御に使われるコンピューター。

*3 畑ケさん本人にこの事を知らせると「やっちまったぁぁ」と恥ずかしがっておられましたが、本書でフィードバック初心者の方に勇気を持ってもらうための礎になっていただきました。合掌。

2020-03-02

ノータブルコード4 - NULLよりも名前付きの番兵オブジェクト

MroongaというMySQLのストレージエンジンを開発している須藤です。MySQLのAPIはよく変わるのでMroongaの開発をしているとMySQLのソースコードを読む機会がよくあります。今日、MySQLのコードを読んでいて「お！」と思うコードがあったので4回目のノータブルコードとして紹介します。

MySQLは基本的なデータ構造も独自に実装していることが多いです。今日紹介するListも独自に実装しています。

多くの場合、リストは次のように「要素データへのポインタ」と「次の要素へのポインタ」を持つ構造をつなげて実装します。

struct List {
  void *data;
  List *next;
};

そして、リストの終端にNULLを置いてリストの終わりを表現します。

if (list->next) {
  printf("have more elements\n");
} else {
  printf("no more elements\n");
}

MySQLのリストの実装はNULLではなくリストの終端を示す番兵オブジェクトを使っていました。

extern MYSQL_PLUGIN_IMPORT list_node end_of_list;

class base_list {
  inline void empty() {
    elements = 0;
    first = &end_of_list;
    last = &first;
  }
};

私が「お！」と思ったのはGDBでデバッグしていたときです。GDBではpで出力したアドレスが既知のグローバル変数や関数などの場合はその名前も出力してくれます。ここでend_of_listという名前が出てきたのです。

(gdb) p (((const Item_cond *)select_lex->where_cond())->argument_list()->first->next->next
$1 = (list_node *) 0x555557f77550 <end_of_list>
(gdb) p (list_node *)0x555557f77550
$2 = (list_node *) 0x555557f77550 <end_of_list>

->nextとしたらNULLが返ってきても「あぁ、ここでリストは終わりなんだな」ということはわかるのですが、end_of_listという名前が見えてもたしかにリストが終わりだとことがわかるなと思いました。リストのときはNULLで十分だとは思いますが、もう少し複雑なもののときはNULLよりもなにか名前が付いた番兵オブジェクトを使うとデバッグが捗るときがあるんじゃないかと思いました。このテクニックを使う機会を見つけることが楽しみです。

今回はMySQLのリスト実装のコードで「お！」と思った名前付きの番兵オブジェクトを紹介しました。みなさんもNULLではなく名前付きの番兵オブジェクトを使った方がよさそうなケースがないか考えてみてください。

ところで、そろそろみなさんも自分が「お！」と思ったコードを「ノータブルコード」として紹介してみたくなってきませんか？ということで、このブログへの寄稿も受け付けることにしました。まだ仕組みは整えていないのですが、とりあえず、 https://gitlab.com/clear-code/blog/issues にMarkdownっぽいマークアップで書いた原稿を投稿してもらえばいい感じに調整してここに載せます。寄稿したいという人がたくさんいるならもう少しちゃんとした仕組みを整えようと思っていますので、興味のある人はご連絡ください。寄稿してもらった記事の著作者は作者本人のままですが、ライセンスはCC BY-SA 4.0とGFDL（バージョンなし、変更不可部分なし、表表紙テキストなし、裏表紙テキストなし）のデュアルライセンスにしてください。参考：ククログのライセンス

それでは、次のノータブルコードをお楽しみに！

2020-03-03

ノータブルコード5 - Lispとシェルスクリプトのキマイラ

今回紹介するコードは、エディンバラ大学が開発した音声合成ライブラリFestivalからのコードです。このライブラリには、テキストファイルを音声に変換する「text2wave」という実行ファイルが付属しています。このファイルの冒頭部分を引用すると次のようになっています。

#!/bin/sh
"true" ; exec /bin/festival --script $0 $*
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;-*-mode:scheme-*-
;;                                                                       ;;
;;                Centre for Speech Technology Research                  ;;
;;                     University of Edinburgh, UK                       ;;
;;                       Copyright (c) 1996,1997                         ;;
;;                        All Rights Reserved.                           ;;
...

;;; Because this is a --script type file I has to explicitly
;;; load the initfiles: init.scm and user's .festivalrc
(load (path-append libdir "init.scm"))

;;; Process command line arguments
(define (text2wave_help)
  (format t "%s\n"
  "text2wave [options] textfile
  Convert a textfile to a waveform
  Options

最初の2行を見て「ああこれはシェルスクリプトなんだな」と思っていると、突然3行目から Lisp/Scheme のコードが始まってビックリさせられます。それ以降のコードはSchemeのプログラムになっていて、シェルスクリプトの面影は影も形もなくなってしまいます。上の抜粋からも、ごく普通のシェルスクリプトの書き出しから、シームレスにSchemeのS式の世界に突入していることがご確認いただけると思います。

これはどういう仕組みで動いているんだろう？というのが、今回の記事のテーマです。

シェルスクリプトとしての実行プロセス

この謎を解き明かすカギは、最初の2行にあります。このスクリプトを「/bin/text2wave test.txt」として実行した時の流れを追ってみましょう。

#!/bin/sh
"true" ; exec /bin/festival --script $0 $*

まず、オペレーティングシステムのプログラムローダーは最初の1行目を見て「これは/bin/shで実行するコードだ」と判断します。ですので、このファイル全体が（最初の見立て通り）まずはシェルスクリプトとして解釈されることになります。

そこで2行目に目を移すと、シェルスクリプトではセミコロン ; はコマンドの区切りを示すので、この行は2つのコマンドから構成されていることが分かります。このうちの、前半部分は特に何もせず成功ステータスコードを返すtrueコマンドなので*1、実行だけされて次に移ります。

これに対して、後半部分にはもっと意味のありそうなコマンドが書かれています。まずこのコマンドの中のシェル変数に注目すると $0 は実行されているプログラムを表すので「/bin/text2wave」に、$* はコマンドライン引数を表すので「test.txt」にそれぞれ置換されます。いいかえると、この部分は次のようなコマンド行に展開されることになります。

exec /bin/festival --script /bin/text2wave test.txt

冒頭のexecはシェル標準のコマンドで、指定した実行プログラムで実行中のプロセスの内容を置き換えます。ですので、このコマンドが実行されると、シェルスクリプトとしての実行はひとまず終了になります。

Schemeスクリプトとしての評価

シェルスクリプトの最後で実行された /bin/festival に着目しましょう。これは、音声合成ライブラリの実行バイナリで、引数「--script」で与えられたファイルをSchemeスクリプトとして処理します。ここでは /bin/text2wave を指定しているので、最初にシェルスクリプトとして評価したスクリプトが（今度はSchemeのスクリプトとして）再び頭から解釈されることになります。

このSchemeインタプリタによる実行評価は次のように進行します。

まず、大抵のLisp処理系は#!をコメント行として扱います。
- これは言語の仕様ではありませんが、スクリプト言語としての用途を考慮して、そのように実装されていることが多いです。
- FestivalのSchemeインタプリタも同様の振る舞いをするので、1行目はコメントとして無視されます。
2行目の前半部分については、Schemeでは"true"は文字列リテラルなので、評価だけして素通りします。
2行目の後半部分は重要なポイントで、実はSchemeではセミコロンはコメントの開始を表します。 従って、execから行末までの部分はコメントとして無視されます。

そこから後の部分は普通のSchemeプログラムなので、普通に実行されることになります。

話をまとめると、このスクリプトは (1) シェルスクリプトとして実行することもできるし、(2) Schemeスクリプトとしても実行できるという実に不思議なプログラムなのです。この特筆すべき性質によって、Schemeとシェルスクリプトというまったく性質の異なる言語が、1つのファイルの中でなめらかに共存できているのです。

なぜこんなことをしているのか？

「確かに面白いテクニックだけど、なぜこんなことをしているの？普通に最初の行で#!/bin/festival --scriptと指定するだけではダメなの？」というのは当然思い浮かぶ疑問です。このFestivalのコードは20年以上前のコードで、すでに実装の背景は分からなくなってしまってるのですが、この構成を採用するメリットは少なくとも2つあります。

システム互換性の問題を回避できる。 Unixでは一般に「#!/path/to/program」という一行をスクリプトの冒頭につけることで、実行するプログラムを指定できますが、実は、この仕組みには明確な仕様がなく、具体的な振る舞いはシステムによってまちまちです（例えば、古いOSだと実行ファイルのパスの後に引数を指定できなかったりします）。この方式だと#!/bin/shさえ上手く解釈されれば、あとはシェルスクリプトで呼び出しを制御するので、非常に広い範囲のUnixシステムでポータブルに動作することが期待できます。
実行プログラムに渡す引数を柔軟に調整できる。 最終的に本体ファイル /bin/festival を呼び出すのはシェルスクリプトなので、実行時のパラメータをいかようにも制御できます。シェルの制御構文を使えば、条件分岐で与える引数を動的に変えることもできます。これは通常のやり方では実現できないポイントです。

まとめ

今回は音声合成ライブラリのFestivalから、Lispとシェルがなめらかに統合された、ギリシャ神話の怪物キマイラのようなコード（頭部はシェルスクリプトで胴体はSchemeです！）をご紹介しました。

皆さんはこのコードを読んでどのような感想を抱きましたか？ノータブルコードのコーナーでは皆さんの寄稿も受け付けていますので、ご意見や「これをぜひ紹介したい」というコードがあれば、ぜひともお寄せください。

*1 (3/17追記) 最初の公開版では「単なる文字列リテラルで、特に変数に代入もされていないので」と説明していましたが、コメントの指摘の通り、誤りのため修正しています。ご指摘ありがとうございます！

2020-03-10

ノータブルフィードバック6 - 初回使用時のつまずきを減らす提案

結城です。

ノータブルコードに便乗して、実際のOSSのフィードバックを見て「ノータブルフィードバック」と題してお届けする記事の6回目として、今回は、[株式会社アカツキさんの社内で実施したOSS Gateワークショップ][20190529]の中で実際に行われた、Webページ上でマウスカーソル（ポインタ）をかざした位置の語句を辞書で引いて結果をポップアップ表示する「Mouse Dictionary」というGoogle Chrome/Firefox用の拡張機能での、「初回使用時にポップアップが真っ白になってしまう」という現象に対するフィードバックをご紹介します。

実際の報告

■タイトル

White screen shown in the first boot

■説明

Steps to Reproduce

Install Chrome (ver. 72.0.3626.109 Official Build 64bit) into MacOSX 10.14.3 .

Install Mouse Dictionary (ver. 1.1.9) from Chrome Web Store.

Click extension icon of Mouse Dictionary, and open the popup window.

Point any English term.

Expected Result

Shown translated sentence of English term in the popup window.

Actual Result

White screen shown in the popup window.

Suggestion

Add how to installation (ex. "Open option menu on the first boot.") in the store page.

Or, add description (ex. "Not initialized. Please open option menu.") in the not initialized popup window.

再現手順

MacOSX 10.14.3 に、Chromeのバージョン：72.0.3626.109（Official Build）（64 ビット）をインストールする

chromeウェブストアから Mouse Dictionary （バージョン：1.1.9）を拡張機能としてインストールする

拡張機能一覧から Mouse Dictionary のアイコンをクリックして、ポップアップウィンドウを立ち上げる

ポップアップウィンドウが立ち上がった状態でウェブページ内の任意の英単語にマウスカーソルを合わせる

期待する結果

Mouse Dictionary のポップアップウィンドウに、翻訳結果が表示される

実際の結果

ポップアップウィンドウ内は白紙のまま、何も表示されない

提案

最初にオプションメニューを開くことが必須ということを、ストアページの説明文に記載してはどうでしょうか

もしくは、辞書情報が登録されていないのでオプションメニューを開かなければならない旨を、ポップアップウィンドウに表示してはどうでしょうか

注目したい点

日本語でも書く

OSS Gateワークショップの中で行ったフィードバックなので、報告の仕方は「再現手順、期待する結果、実際の結果」という基本のフォーマットに則っています。

ここで注目したいのは、本文を英語と日本語の2パターンで書いているということです（ここに掲載するために翻訳したのではなく、元々の報告の時点で両方載っています）。これは、説明文からリンクされている開発者の方による解説記事が日本語で書かれており、作者の方が日本語話者の方だということが分かっていたためです。

OSSへのフィードバックは、書ける場合は英語で書いておいたほうが望ましいです。というのも、英語を読み書きできる人と日本語を読み書きできる人とでは前者の方が圧倒的に数が多く、日本語だけで報告を書いていると、同じ問題に遭遇した人が「既存の同様の報告」にたどり着けない恐れがあるからです。

とはいえ、英語を書くことに不慣れな人は、自分の伝えたかったことをきちんと英語で表現できているか不安なものです。この事例のように作者の方が日本語話者と分かっている場合には、両方の言語で報告を書いておくことで、万が一の場合の誤解を防げるという安心感を持って報告できるでしょう。

使い始めのつまずきを報告している

第1回でとりあげたOCamlへのフィードバックでは、インストール後のバージョン確認の手順の間違いをフィードバックしましたが、今回もそれと同様に、初めて使うときにつまずく人の多そうな点をフィードバックしています。

一般ユーザーでも開発者でも、「説明書を読まずに使い始める」人は一定数います（筆者もそうです）。そのような人にとっては、説明を読んで使うことが前提のツールは使い始めていきなり「詰んで」しまう、ということになりがちです。初期化用のウィザードやチュートリアルはその最も丁寧な対応の例ですが、そこまで凝った対応でなくても、この提案のように「案内のメッセージを出す」だけでも、ほとんどのユーザーにとっては大きな助けになるでしょう。

提案も書く

また、報告の最後に 「提案」として改善案を示している ところもポイントです。操作に対する「期待される結果」は「翻訳結果が表示されること」なのですが、初回使用時という場面では、初期設定なしにそのような結果を得るのは難しいです。そこで、この報告では次善の策として、ユーザーがしなければならないことの案内を明示するのはどうか、と提案しています。

開発者側で気を回して「こうなっているといいのでは」と推測して実装した結果が、実際のユーザーのニーズに合致していなかった、ということは度々あります。ユーザー自身が「どうなっていると嬉しい」という内容を詳しく伝えることで、そのような無駄足を踏まずに済むと言えます*1。

まとめ

ノータブルフィードバックの6回目として、Google Chrome/Firefox向け拡張機能の初回使用時の動作についてのフィードバックをご紹介しました。

このような「身近なところで遭遇したつまずきをOSS開発プロジェクトにフィードバックする」ということをテーマに、まだOSSにフィードバックをしたことがない人の背中を押す解説書「これでできる！はじめてのOSSフィードバックガイド～ #駆け出しエンジニアと繋がりたいと言ってた私が野生のつよいエンジニアとつながるのに必要だったこと～」を、電子書籍としてリリースしました。本記事の内容はこの本からの抜粋となっています。4月5日までオンライン開催されている「技術書典応援祭」内のマーケットにて紙版＋電子書籍（または電子書籍のみ）を購入頂けますので、ゆっくりオフラインで読みたい方はぜひチェックしてみて下さい。

*1 ただ、開発者側の視点では、ユーザーから寄せられた提案にそのまま従うことが必ずしも正解とは限らない、ということも言えます。というのも、ユーザー自身の発想が特定の場面やそれまでの経験に囚われている場合、言葉として表現された物が本来のユーザー自身のニーズからかけ離れてしまっていることがあるからです。開発者はユーザーからの提案を判断材料の一つとしつつ、その提案が発せられた背景をきちんと分析し、常に最適な解決策を考えるよう努める必要があります。

2020-03-23

ノータブルフィードバック7 - 開発者の環境では必要ない改善の提案

結城です。

ノータブルコードに便乗して、実際のOSSのフィードバックを見て「ノータブルフィードバック」と題してお届けする記事の7つ目は、前回フィードバック対象となったMouse Dictionaryに対して筆者が別に行った、連続した一連のフィードバックです。

実際の報告

最初に行ったのは、前回のフィードバックで表示されるようになった初期設定の案内文の内容が、Firefoxでの実際のUIに整合しない状態だったために行ったフィードバックです。

■タイトル

初回使用時の案内がFirefoxでの状況にマッチしていない

■説明

初回使用時に辞書が未設定だと、ページ内に開いたポップアップの中に「初めに辞書データをロードしてください(拡張のアイコンを右クリック→「オプション」)」という案内のメッセージが表示されます。
しかしながら、Firefoxにはこのメニュー項目がありません。実際には、

アイコンを右クリック→「拡張機能を管理」を選択→「...」をクリック→「オプション」を選択

とする必要があります。

初回使用時に戸惑ったため、メッセージを各実行環境向けに変えることが望ましいと思われます。

このイシューに対応するプルリクエストは以下の内容でした。

■タイトル

Show initial setup guide for Firefox
≪Firefox用の初期設定案内を表示する≫

■説明

#32 に対する実装の提案となります。
こんな感じでいかがでしょうか？

■変更内容

メッセージの定義部にFirefox用のメッセージを追加し、実行環境によってメッセージを切り替えるようにした。

そのレビューの中で「コーディングスタイルをprettier準拠に揃えて欲しい」という指摘を受けたのですが、それをきっかけに作成した別のプルリクエストが、次の物です。

■タイトル

Add prettier
≪prettierを追加する≫

■説明

#33 でコーディングスタイルのご指摘をいただきましたが、コーディングスタイルもlintの一環とすることでコーディングスタイルの揃え忘れを減らせるのではないかと思いました。
いかがでしょうか？

変更内容:
package.jsonの文法チェック用の指定に変更を加え、コーディングスタイルをチェックするようにした。

注目したい点

状況に合わせたフィードバックの仕方

コミットメッセージから自動的に埋められたプルリクエストのタイトルを除いて、英語と日本語の併記ではなく、日本語だけでの報告となっています。これは、

プロジェクトオーナーが日本語話者だと分かっている。
小規模な問題で、すぐにプルリクエストを出して問題を解消するつもりなので、イシューが長期に渡って残ることをあまり考慮しなくてもよさそう。

という前提があったためです。また、説明文については、「再現手順」「実際の結果」「期待される結果」を見出しを立てて強調するということもなく、自然文の中に入れてサラッと流してしまっています。これも、「初回起動時の一幕」という前提があるため、要点さえ押さえておけば伝わるだろう、という判断に基づいています。

フィードバックの経験が少ない状況では、どの情報を含めてどの情報を省略するべきかということの判断基準が不足していますので、下手をすると「その情報じゃなくて、こっちをむしろ残すべきだった」というような情報を省略してしまいかねません。そのため、「これでできる！はじめてのOSSフィードバックガイド」では「情報不足よりは情報過多の方がよい」という考えに基づいて、基本的な報告のフォーマットを紹介しています。

そのような取捨選択の感覚は、恐らく、報告をする立場だけだとあまり身に付きません。というのも、フィードバックは 「フィードバックを受ける側（開発者）にとって助けとなる内容」であること が望ましく、「どういう報告なら開発者は嬉しいか」ということは、突き詰めると開発者でなければ分からないからです。筆者の場合は、自分自身が開発者としてフィードバックを受ける機会が重なる中で、「こういう場面では、この情報をもらっても開発者の自分はあまり嬉しくない」という経験を得ており、それが取捨選択の判断基準になっています。

フィードバックの連鎖と、開発者以外の人に役立つフィードバック

また、もう一つ注目して欲しいのは、「プルリクエストに対するレビューを受けたときに気が付いたことを、別のプルリクエストで即座に（カジュアルに）フィードバックしている」という点です。1つフィードバックをすると、それがまた次のフィードバックにつながるということは、非常によくあります。

そうして行った2つ目のプルリクエストは、実はプロジェクトオーナーの方にとっては直接的には必要のない変更です。筆者は特に文法チェックや整形などの開発支援の仕組みを持たないテキストエディタを使っていますが、プロジェクトオーナーの方ご自身は、コーディングスタイルの整形はVSCodeの設定でファイルの保存時に行うようにされているからです。

このようなときには、自分が使っているテキストエディタの設定を変更したり、そのような設定がなければ別のテキストエディタへ乗り換えたりと、自分の手元の環境の範囲で改善を図る方が多いでしょう。しかしここでは、それを「個人の環境設定の問題」とは捉えず、「プロジェクトオーナーがプルリクエストの内容を一々チェックしないといけないという、プロジェクトの問題」と捉え、それを解消するプルリクエストを出したのでした。「問題をプロジェクトの問題だと捉えると、フィードバックできる点になる」ということの実例と言えるでしょう。

まとめ

ノータブルフィードバックの7回目として、フィードバックの連鎖の中で行った、「開発者の方にとって直接的には役には立たないけれども意味のある改善」の例をご紹介しました。

このような「身近なところで遭遇したつまずきをOSS開発プロジェクトにフィードバックする」ということをテーマに、まだOSSにフィードバックをしたことがない人の背中を押す解説書「これでできる！はじめてのOSSフィードバックガイド～ #駆け出しエンジニアと繋がりたいと言ってた私が野生のつよいエンジニアとつながるのに必要だったこと～」を、電子書籍としてリリースしました。本記事の内容はこの本からの抜粋となっています。4月5日までオンライン開催されている「技術書典応援祭」内のマーケットにて紙版＋電子書籍（または電子書籍のみ）を購入頂けますので、ゆっくりオフラインで読みたい方はぜひチェックしてみて下さい。