What did you expect to happen: バグ報告の基本、期待した動作と実際の動作

今日の英語表現 2/30 · ステップ: Issueを開く 例文はすべてこの記事のために作成したものです。実際のレポジトリのコメントを転載したものではなく、バージョンやコマンドは例です。

目次

• 一目でわかる要約
• 1. 意味とニュアンス
• 2. 例文
• 3. 似た表現との違い
• 4. 日本人がよく犯すミス
• 5. 一行練習
• 模範解答
• 参考

一目でわかる要約

1. 意味とニュアンス

バグ報告においてメンテナーが最も最初に知りたいのは次の2つです。 実際に何が起きたのか(actual behavior)、そして 報告者が何が起きるべきだと考えていたのか(expected behavior)です。両者のギャップこそがバグの定義です。期待がドキュメントと異なっていれば、バグではなく誤解である可能性もあるため、期待を分けて書いておけば、メンテナーから「これは意図された動作です」と素早く回答をもらえることもあります。

Kubernetesのバグ報告テンプレートは最初の3つの項目を What happened?, What did you expect to happen?, How can we reproduce it (as minimally and precisely as possible)? にしています。多くのリポジトリが同じ構造を採用しています。テンプレートがないリポジトリでも、これら3つの見出しをそのまま使うことで読みやすいIssueになります。

時制に注意してください。実際の動作はすでに起きたことなので過去形(The pod was evicted)や現在形(The controller logs an error)を使います。期待した動作には should や expected ... to を使います(The VM should stay running, I expected the backup to complete).

2. 例文

状況 1: Issue本文の2つの項目

What happened: After upgrading to v1.3.0, virtctl restart returns immediately, but the VM stays in Stopped.

What did you expect to happen: The VM should be restarted and reach Running, as it did on v1.2.x.

前のバージョンではどうだったか(as it did on v1.2.x)を付け加えると、回帰バグ(regression)であることがすぐにわかります。

状況 2: Expected と Actual を小見出しに分ける場合

Expected behavior

The scheduled backup completes and a new object appears in the bucket.

Actual behavior

The backup stays in running for more than an hour, and no object is written.

状況 3: 他人のIssueに質問する場合

Thanks for the report. Could you clarify what you expected to happen here? The current behavior matches the docs, so I want to make sure I understand the use case.

質問する側でもこの表現を使います。攻撃せずに期待を確認するための丁寧な方法です。

3. 似た表現との違い

• Steps to reproduce. 再現手順です。期待と実際の間に置かれる項目であり、コマンドを番号付きリストで記載します。
• Observed behavior. actual behavior と同じ意味です。少しフォーマルで、観察された事実であるというニュアンスが強くなります。
• Desired behavior. 機能要望(feature request)で使用します。バグ報告における expected は「本来そうあるべきもの」であり、desired は「今後こうなってほしいもの」です。

4. 日本人がよく犯すミス

• It doesn't work. このような一行報告は、メンテナーに同じ質問を2、3回聞き返す手間をかけさせてしまいます。何がどのように動作しないのかを記述する必要があります。
  • 修正した文: The webhook rejects valid manifests with field is immutable. I expected the update to be accepted because only the label changed.
• I expected that it will be restarted. 時制が一致していません。過去の期待なので would を使うか、to不定詞を使います。
  • 修正した文: I expected it to be restarted.
• Expected result is VM is running. 冠詞と接続が抜けており、文が途切れています。
  • 修正した文: The expected result is that the VM is running.
• Please kindly check this bug ASAP. 催促と過剰な丁寧さが混ざっています。影響が大きい場合は、その影響を事実として記載します。
  • 修正した文: This blocks upgrades for clusters using the default storage class.

5. 一行練習

次の内容をIssueの2つの項目に分けて英語で書いてみてください。

バックアップポリシーを削除したのに、予約されたバックアップが作成され続けています。ポリシーを削除したら、予約バックアップも停止するべきだと思いました。

模範解答

What happened: After deleting the backup policy, scheduled backups are still being created.

What did you expect to happen: Deleting the policy should stop the scheduled backups.

are still being created は「今も作られ続けている」という進行形の受動態です。後ろの文は「〜すべきである」という期待なので should を使用します。

Titiの一言 期待したことと実際に起きたことを2行に分けるだけでも、バグ報告の半分は完了です。

参考

• Kubernetesバグ報告テンプレート(bug-report.yaml): https://github.com/kubernetes/kubernetes/blob/master/.github/ISSUE_TEMPLATE/bug-report.yaml
• GitHub Docs, Issueテンプレートの設定: https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository