How to write a good bug report
A bug is above all reproducible. To be reproducible, a bug report must be written so that anyone can repeat the steps, regardless of their level of experience.
A well written bug report will consist of 4 basic parts:
- Summary: How would you describe the bug, in approximately 60 or fewer characters?
- Reproduction Steps: These are the steps that must be taken to reproduce the bug.
- Actual Behavior: This is the observed result of the reproduction steps, i.e. the bug.
- Expected Behavior: This is the expected behavior of the reproduction steps, based on your experience with the program/app.
Additional optional parts to a bug report:
- Notes: usually listed at the bottom of the bug report, these notes indicate other information the bug report writer may feel is useful, but does not belong in the report proper. Items such as ‘happened on [X] device that I have tested it with’ or ‘does not always occur, happens 1 out of 3 attempts’ would be appropriate for notes.
- Additional information: Used to list things such as exception details, so that this text does not clutter up the middle of the bug write up. It is good form to indicate that an exception occurred in the ‘Actual Behavior’ part of a bug report, and to put the contents of the exception in the additional information area of the bug report further down. This allows someone to read the bug report quickly, without getting bogged down in the exception text.
Summary:
A good summary should quickly and uniquely identify a bug report. It should explain the problem, not your suggested solution.
- Good: "Opening [X] library in the IDE causes IDE to crash with [X] error"
- Bad: "Software crashes"
- Bad: "This should work with my app"
Reproduction Steps:
These steps should start at the most basic starting point and progress through the shortest number of steps possible to culminate in the actual behavior observed. Often this means that the first steps are the same, i.e. install build x, and run build x with hardware y. This is to be expected, the person who later follows this bug needs to know where to start and how to reliability reproduce the bug in question. Reproduction steps should always be listed as one per line.
Actual Behavior:
This is where you describe in as much detail as necessary what happened after the last step in the reproduction steps was executed. I.e. the bug, what did you see, what error was observed, and how was it displayed to the user.
Expected Behavior:
This is where you describe the result you expected after the last reproduction step was executed. I.e. after I clicked on Compile and Run, I expected XYZ to happen. This allows the person/people evacuating the bug to know what the user was expecting, so they can evaluate the validity of the bug.
Example of a poorly documented bug:
Reflection library doesn't work on my phone/app
This bug report raises more questions than it answers:
- What version of B4A or the library in question are you running?
- What hardware are you using it with?
- What value was believed to be wrong?
- What did the user expect to happen?
Example of the same bug with a well written report:
Reproduction Steps:
1: Install and launch B4A version (x.xx)
2: Click the Reflection library checkbox in the library tab
3: Ensure reflection library is version (x.xx)
4: Copy and paste the following code into your project (or open this source zip)
5: Compile and run the project
6: Observe XXXX error on line YYYYY
Actual Behavior:
You receive and error message indicating that ’Java runtime is tired and wants a Pepsi’.
Expected Behavior:
I expected the reflection library to make my reflection in the mirror look like Justin Timberlake.
Note: please feel free to suggest any changes to this post.
A bug is above all reproducible. To be reproducible, a bug report must be written so that anyone can repeat the steps, regardless of their level of experience.
A well written bug report will consist of 4 basic parts:
- Summary: How would you describe the bug, in approximately 60 or fewer characters?
- Reproduction Steps: These are the steps that must be taken to reproduce the bug.
- Actual Behavior: This is the observed result of the reproduction steps, i.e. the bug.
- Expected Behavior: This is the expected behavior of the reproduction steps, based on your experience with the program/app.
Additional optional parts to a bug report:
- Notes: usually listed at the bottom of the bug report, these notes indicate other information the bug report writer may feel is useful, but does not belong in the report proper. Items such as ‘happened on [X] device that I have tested it with’ or ‘does not always occur, happens 1 out of 3 attempts’ would be appropriate for notes.
- Additional information: Used to list things such as exception details, so that this text does not clutter up the middle of the bug write up. It is good form to indicate that an exception occurred in the ‘Actual Behavior’ part of a bug report, and to put the contents of the exception in the additional information area of the bug report further down. This allows someone to read the bug report quickly, without getting bogged down in the exception text.
Summary:
A good summary should quickly and uniquely identify a bug report. It should explain the problem, not your suggested solution.
- Good: "Opening [X] library in the IDE causes IDE to crash with [X] error"
- Bad: "Software crashes"
- Bad: "This should work with my app"
Reproduction Steps:
These steps should start at the most basic starting point and progress through the shortest number of steps possible to culminate in the actual behavior observed. Often this means that the first steps are the same, i.e. install build x, and run build x with hardware y. This is to be expected, the person who later follows this bug needs to know where to start and how to reliability reproduce the bug in question. Reproduction steps should always be listed as one per line.
Actual Behavior:
This is where you describe in as much detail as necessary what happened after the last step in the reproduction steps was executed. I.e. the bug, what did you see, what error was observed, and how was it displayed to the user.
Expected Behavior:
This is where you describe the result you expected after the last reproduction step was executed. I.e. after I clicked on Compile and Run, I expected XYZ to happen. This allows the person/people evacuating the bug to know what the user was expecting, so they can evaluate the validity of the bug.
Example of a poorly documented bug:
Reflection library doesn't work on my phone/app
This bug report raises more questions than it answers:
- What version of B4A or the library in question are you running?
- What hardware are you using it with?
- What value was believed to be wrong?
- What did the user expect to happen?
Example of the same bug with a well written report:
Reproduction Steps:
1: Install and launch B4A version (x.xx)
2: Click the Reflection library checkbox in the library tab
3: Ensure reflection library is version (x.xx)
4: Copy and paste the following code into your project (or open this source zip)
5: Compile and run the project
6: Observe XXXX error on line YYYYY
Actual Behavior:
You receive and error message indicating that ’Java runtime is tired and wants a Pepsi’.
Expected Behavior:
I expected the reflection library to make my reflection in the mirror look like Justin Timberlake.
Note: please feel free to suggest any changes to this post.
Last edited:
