how-to-make-a-bug-report.md (7395B)
1 How to Make a Bug Report 2 ---------------- 3 4 **Note: We are currently a few devs active on the project. We can’t 5 answer and tags each issues opened, but we read it. A good issue provide 6 an important feedback and thank you for that, any feedback is 7 appreciated.** 8 9 Setup your environment 10 ~~~~~~~~~~~~~~~~~~~~~~ 11 12 - Be ready for data loss. Backup your account and link your account to 13 as many devices as possible. 14 - Install the latest version (or even a beta version) of Jami. It is 15 useless to report bugs on older versions. 16 17 How to report a bug 18 ~~~~~~~~~~~~~~~~~~~ 19 20 0. Create an account on `our git 21 repository <https://git.jami.net/users/sign_in>`__ (if it is not already 22 done) 23 24 1. Choose the right project to post your issue in: \* `The Android 25 client <https://git.jami.net/savoirfairelinux/ring-client-android>`__ \* 26 `The Windows 27 client <https://git.jami.net/savoirfairelinux/ring-client-windows>`__ \* 28 `The Linux 29 client <https://git.jami.net/savoirfairelinux/ring-client-gnome>`__ \* 30 `The iOS 31 client <https://git.jami.net/savoirfairelinux/ring-client-ios>`__ \* 32 `The macOS 33 client <https://git.jami.net/savoirfairelinux/ring-client-macosx>`__ \* 34 `The Jami project in general (or if you are not 35 sure) <https://git.jami.net/savoirfairelinux/ring-project>`__ \* `If you 36 know what you are doing you may choose one of the other 37 projects <https://git.jami.net/>`__ 38 39 2. If you have multiple issues, please file separate bug reports. It 40 will be much easier to track bugs that way. 41 42 3. Title is an explicit summary of the bug (e.g.: header bar is too big 43 due to icon size) 44 45 4. Figure out the steps to reproduce the bug: 46 47 - If you have precise steps to reproduce it — great! — you’re on your 48 way to creating a useful bug report. 49 - If you can reproduce occasionally, but not after following specific 50 steps, you must provide additional information for the bug report to 51 be useful. 52 - If you can’t reproduce the problem, there’s probably no use in 53 reporting it, unless you provide unique information about its 54 occurrence. 55 - If the bug leads to other bugs afterward that you can’t reproduce 56 some other way, there’s probably no use in reporting it. 57 58 5. Make sure your software is up to date. Ideally, test an 59 in-development version to see whether your bug has already been fixed 60 61 6. Try to isolate from environment and reproduce (ie: test on multiple 62 devices) 63 64 7. Describe your environment(s) by specifying the following: 65 66 - OS version 67 - precise device model (important for mobile devices) 68 - if you are using a beta version 69 - what build you are using (from ring.cx, F-droid, Play Store, App 70 store, you own…). If you have built your own version of Ring, please 71 specify the exact dring version (LibRing or Daemon) and client 72 version (You can obtained it with ``dring -v`` and ``jami-gnome -v``. 73 But note that our packages are updated quite often) and the Git 74 commit. 75 - network conditions: Are both devices on the same local network? 76 Different networks? Is one or both behind NAT? Are you using LTE? 77 Wifi? 78 - other elements if needed: SIP provider, hardware… 79 80 Writing a clear summary 81 ~~~~~~~~~~~~~~~~~~~~~~~ 82 83 How would you describe the bug using approximately 10 words? This is the 84 first part of your bug report a developer will see. 85 86 A good summary should quickly and uniquely identify a bug report. It 87 should explain the problem, not your suggested solution. 88 89 :: 90 91 Good: "Cancelling a file transfer crashes Ring" 92 Bad: "Software crashes" 93 94 :: 95 96 Good: "All calls hang up after 32 seconds" 97 Bad: "Not able to call my friends" 98 99 Writing precise steps to reproduce 100 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 101 102 - How can a developer reproduce the bug on his or her own device? 103 104 Steps to reproduce are the most important part of any bug report. If a 105 developer is able to reproduce the bug, the bug is very likely to be 106 fixed. If the steps are unclear, it might not even be possible to know 107 whether the bug has been fixed. We are totally aware that some bugs may 108 look obvious to you, but they are probably related to your environment. 109 The more precise you are, the quicker the bug is fixed. 110 111 - What should you include in a bug report? 112 113 Indicate whether you can reproduce the bug at will, occasionally, or not 114 at all. Describe your method of interacting with Ring in addition to the 115 intent of each step. After your steps, precisely describe the observed 116 (actual) result and the expected result. Clearly separate facts 117 (observations) from speculations. 118 119 Good : 120 ^^^^^^ 121 122 I can always reproduce by following these steps: 123 124 :: 125 126 1. Start Ring by clicking on the desktop icon 127 2. Start a new conversation with anyone 128 3. Click file transfer icon 129 130 Expected results: A window opens and ask me to choose a file to send. 131 Actual results: When I click the file transfer icon, nothing happens. 132 133 Bad : 134 ^^^^^ 135 136 :: 137 138 Try to transfer a file 139 It doesn't work. 140 141 Obtained Result 142 ~~~~~~~~~~~~~~~ 143 144 Please include: 145 146 - The daemon (or LibRing) and client debug logs. 147 - The core dump if one was produced. 148 149 Expected Result 150 ~~~~~~~~~~~~~~~ 151 152 It’s a description of expected or desired behaviour. 153 154 Providing additional information 155 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 156 157 The following information is requested for most bug reports. You can 158 save time by providing this information below the Expected results. 159 160 Logs 161 ^^^^ 162 163 On GNU/Linux 164 '''''''''''' 165 166 Classic logs (by default logs only >= warning are loggued): 167 168 :: 169 170 journalctl --since "24h ago" | grep dring 171 172 Full log: Since the Ring GUI and daemon are separated processes, the 173 easiest way to get logs from both is to start them one at a time, 174 manually. 175 176 1. Ensure that no ring client or daemon instances are running with 177 ``ps aux | grep ring`` 178 179 - Ring may still be running even if no windows are open depending on 180 your preferences. 181 - If either client or daemon are running, kill them with 182 ``kill PID`` 183 184 2. On one terminal, start the daemon with ``dring -d -c`` 185 186 - This executable is normally not in the PATH, and on the Ubuntu 187 packages, it is located at 188 ``/usr/lib/x86_64-linux-gnu/dring -d -c`` or 189 ``/usr/lib/ring/dring -d -c`` 190 191 3. In another terminal, start the client with (here is a Gnome example) 192 ``jami-gnome -d`` 193 194 For getting a backtrace, you can run the program inside gdb: 195 196 `gdb -ex run jami-gnome\ ``or``\ gdb -ex run –args /usr/lib/ring/dring 197 -cd\` 198 199 When it does crash, you can type ``bt`` then press **Enter**. And copy 200 the backtrace to the issue. (or ``thread apply all bt`` is event better) 201 202 On Mac OS 203 ''''''''' 204 205 Open the Terminal app and launch Ring with 206 ``/Applications/Ring.app/Contents/MacOS/Ring`` 207 208 - Open Console 209 - Click on “All messages” 210 - Search field: “Jami” 211 212 On Android (debug builds only) 213 '''''''''''''''''''''''''''''' 214 215 - You need to have adb setup on your computer. 216 - Launch Ring on your smartphone and then execute 217 - ``adb logcat *:D | grep \``\ adb shell ps \| egrep ‘cx.ring’ \| cut 218 -c10-15\` > logring.txt\` 219 - You now have a file containing the log of the client 220 221 For Windows 222 ''''''''''' 223 224 Open a terminal(cmd.exe) and launch Jami.exe with the following options: 225 226 - ``-d`` to open a separate console window to receive logs 227 - ``-f`` to write logs to ``%localappdata%\jami\jami.log`` 228 - ``-c`` to print logs directly to the Visual Studio debug output 229 window