Guide: Reporting Bugs - dsriseah/ursys GitHub Wiki

Bug reports should be entered as a Github Issue with the title "BUG: [description]" and include just three elements:

1. what you expected to see / tried to do
2. what you saw instead (w/ screenshots)
3. detailed steps to reproduce the bug

Additionally, you can provide:

4. a workaround you found to get around the bug
5. how critical the bug is to your workflow

If you want to be an excellent bug reporter, stick to the first three items. It is enough to provide the steps to reproduce the bug and describe what you expected to happen instead.

If you want to be a super-awesome bug reporter, create the issue yourself in the repo. This is where they should go; the person who takes on the issue may rename or reformat it, but you have saved them the trouble of transcribing your verbal report or copy/pasting bits of text from another source.

The bug report itself should be the main text of the Github Issue you have filed, following the guidelines above.

I know it's exciting to be part of the forensic process and solve mysteries, so you can this kind of information as comments:

1. Details unrelated to the actual bug - If you provide information that's NOT STRICTLY RELEVANT to reproducing the bug, do keep it separated from the bug report itself. That way, we don't end up trying to relate that information to the debugging context as we try to understand the report when it has nothing to do with it.

2. Speculating about causes of the bug - Even if you are an experienced programmer, keep your speculation out of the actual bug report and add it as a comment. While inspired guesses are fun, the truth emerges from being about to reproduce the bug using your bug report. Unchecked armchair speculation can lead developers astray. This is particularly the case when the speculation is done by people who did not write the code in question, or are not deeply familiar with the details of its operation. It's fine to post your speculations as a comment though.

Every time you post a good bug report, Sri is happy. Don't commit these bug reporting sins:

1. Describing the bug without providing any other information - Telling us "there is a bug in the program" without any information doesn't help. You are the only one who can tell us where it is.

2. Not capturing visual evidence of the bug - Share a screenshot with us, so when you describe the bug we can see what you are talking about. If there are any error messages, copy the complete error text because it contains information that you may not understand but will save us considerable time. Use your camera phone to take a snapshot if you don't want to hassle with screenshots. Don't summarize or paraphrase. Capture as much as the output as you can, because what you think is the important error might not be the source of it.

3. Not providing specific steps to reproduce the bug - Provide the name of the app, the files you loaded, the buttons you pressed to get to the error state, the webpage link or screen dialog. Confirm that these steps work before you send them.