[Sticky] 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: If possible start the JeeLight.jar with "java -jar JeeLight.jar" to get the log-output or open your ConfigFolder under "Other" and attach your log.txt
A good summary should quickly and uniquely identify a bug report. It should explain the problem, not your suggested solution.
- Good: "Running Ambilight crashes with following log:"
- Bad: "JeeLight crashes"
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. 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.
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.
This is where you describe the result you expected after the last reproduction step was executed. I.e. after I clicked on Start Ambilight, 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:
Scene doesnt work
This bug report raises more questions than it answers 🙂