Submitting useful bug reports

First, thank you many times over for taking the time to file a bug. For the report to be most effective, we've noticed the following characteristics help us get to a solution the fastest.

TL;DR example issue

Everytime there's a food commercial my messages start jiggling.

Steps to reproduce:

1. Open the main conversation list
2. A commercial about food comes on the television in the other room
3. My Signal messages jiggle in the conversation list for a couple seconds

Device info: Nexus 4, stock Android 5.1.1, Signal 3.9.1

App state: Signal messages and calls registered, SMS disabled

Debug log: https://gist.github.com/anonymous/j166l3m3554635

Characteristics

Come up with a descriptive, short title

When you have your title ready please search the issue tracker again using your title to see if there is already an existing issue concerning your bug. If there is please add your findings on that issue. The more useful information an issue has the better change it has to get fixed. If the search yields no duplicates please create a new issue.

Try to reproduce the bug

To fix an issue the developers need to see the bug themselves. Try to find the exact conditions and steps that make the bug happen and then write them down on your issue report. Following your steps the developers can then see what's causing the bug and hopefully fix it.

Capture a debug log

Debug log is like a history which tells what Signal is doing while it's running. If you capture a debug log while a bug is happening it can be extremely useful. A debug log can sometimes be the only way left to analyse what's happening if you are unable to lay out the exact steps that cause the bug. And even if you can reproduce the bug on your device it doesn't guarantee that the same steps cause the bug on the developer's device. Thus it is always helpful to add a debug log to your issue report.

How to capture debug log

1. Go to Signal's Settings
2. Go to Advanced
3. Tap Submit debug log
4. Now you will see the debug log (and you may edit it if you wish)
5. Tap Submit to send the debug log to GitHub as an anonymous log
6. You will see a pop-up window with the link to your debug log
7. Copy the link and paste it to your issue report

Debug log privacy

Debug logs captured within Signal are stripped from personal information. However please note that the last two digits of your and your contacts phone numbers are visible in the logs. This is to help differentiate the contacts. E.g. +1 555 3455 will show as +******55 in the log

Add a screenshot

Sometimes a picture is worth a thousand lines of debug logs (this doesn't mean that you shouldn't add a debug log too :). If the problem is visual and difficult to describe a screenshot can come a long way. Different Android vendors have different ways of taking screenshots. Please check how to do it on your specific device. Usually it's a combination of pressing the volume buttons and power button at the same time.

Plese note that by default Signal disables taking screenshots. To enable them go to Settings -> Privacy and disable Screen security.

Device and app information

• What's your device?
• What Android version is it running?
• What version of Signal do you have?

App state

• Are you registered for Signal messages and calls or do you use Signal just for plain text SMS/MMS?
• What are the relevant settings that you have set that may be related to the issue?
• If this is a bug involving a second party, what's their device/app info and app state?

Advanced capturing

Debug logs with adb

adb logcat

Please note that capturing raw log data with adb may expose private information such as your contacts' phone numbers.

Screeshots with adb

adb shell /system/bin/screencap -p /sdcard/screencap.png && adb pull /sdcard/screencap.png

Video (only for Android 4.4 and up)

A small video or gif can be helpful if the problem is visual and difficult to describe.

adb shell screenrecord /sdcard/screenrecord.mp4

Then pull it from the device.

Animated gifs

If you have ffmpeg and imagemagick, you can quickly convert to gif with:

ffmpeg -i screenrecord.mp4 -r 10 screenrecord%05d.png
convert screenrecord*.png screenrecord.gif
rm screenrecord*.png

Manually making an Animated gif

mkdir tmpScreens
cd tmpScreens
# perform as many screenshots as you need to string together the animated gif:
RIGHTNOW=$(date +%F-%H-%M-%S-%N) bash -c 'adb shell screencap -p | perl -pe "s/\x0D\x0A/\x0A/g" > adb-screenshot-$RIGHTNOW.png'
convert -delay 70 -loop 0 *.png anim.gif