What did you expect to happen: The Basics of Bug Reporting, Expected and Actual Behavior

Today's English Expression 2/30 · Step: Opening an Issue. All example sentences were created for this post. They are not copied from actual repository comments, and versions and commands are examples.

Table of Contents

• Overview
• 1. Meaning and Nuance
• 2. Example Sentences
• 3. Similar Expressions and Differences
• 4. Common Mistakes Made by Koreans
• 5. One-Line Practice
• Sample Answer
• Reference

Overview

1. Meaning and Nuance

What maintainers want to know first in a bug report are two things: what actually happened(actual behavior), and what the reporter thought should happen(expected behavior). The gap between the two is the definition of a bug. If the expectation differs from the documentation, it might be a misunderstanding rather than a bug, so writing down the expectation separately allows maintainers to quickly reply, "This is intended behavior."

The bug reporting template of Kubernetes places the first three fields as What happened?, What did you expect to happen?, and How can we reproduce it (as minimally and precisely as possible)?. Many repositories use the same structure. Even in repositories without a template, using these three headings makes for a readable issue.

Pay attention to tenses. Since the actual behavior has already occurred, use the past tense (The pod was evicted) or present tense (The controller logs an error). For expected behavior, use should or expected ... to (The VM should stay running, I expected the backup to complete).

2. Example Sentences

Scenario 1: Two fields in the issue body

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.

Adding how it behaved in the previous version (as it did on v1.2.x) immediately reveals that it is a regression.

Scenario 2: When dividing Expected and Actual into subheadings

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.

Scenario 3: When asking questions on someone else's 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.

The person asking questions also uses this expression. It is a polite way to check expectations without attacking.

3. Similar Expressions and Differences

• Steps to reproduce. Reproduction steps. This is the section placed between expected and actual behavior, listing commands in a numbered list.
• Observed behavior. Means the same as actual behavior. It sounds slightly more formal and emphasizes observed facts.
• Desired behavior. Used in feature requests. In bug reports, expected means "what it is supposed to do," whereas desired means "what you wish it would do going forward."

4. Common Mistakes Made by Koreans

• It doesn't work. A one-line report forces maintainers to ask the same questions two or three times. You need to write down what is not working and how.
  • Fixed sentence: 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. The tense does not match. Since it is a past expectation, use would or a to-infinitive.
  • Fixed sentence: I expected it to be restarted.
• Expected result is VM is running. Missing articles and connections make the sentence disjointed.
  • Fixed sentence: The expected result is that the VM is running.
• Please kindly check this bug ASAP. A mix of rushing and excessive politeness. If the impact is large, state the impact as a fact.
  • Fixed sentence: This blocks upgrades for clusters using the default storage class.

5. One-Line Practice

Write the following content in English, divided into two issue fields.

I deleted the backup policy, but scheduled backups are still being created. I thought that deleting the policy should also stop scheduled backups.

Sample Answer

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" is a progressive passive voice meaning "they are still being created right now." The second sentence expresses an expectation that something "should" happen, so use should.

Titi's Tip. Simply separating what you expected and what actually happened into two lines solves half of your bug reporting.

Reference

• Kubernetes bug report template (bug-report.yaml): https://github.com/kubernetes/kubernetes/blob/master/.github/ISSUE_TEMPLATE/bug-report.yaml
• GitHub Docs, Configuring issue templates: https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository