Skip to content
Snippets Groups Projects
Unverified Commit f76fe280 authored by Amin Bandali's avatar Amin Bandali
Browse files

Port bug report guide to Sphinx 

Add MyST-Parser and use it to parse CommonMark Markdown.

Change-Id: Ieaa7e869ed68f738db6b655e04b070e58d0c81c0
parent e6152a34
No related branches found
No related tags found
No related merge requests found
Show whitespace changes
Inline Side-by-side
conf.py
+ 6
− 0
View file @ f76fe280
...@@ -22,8 +22,14 @@ copyright = '2018-2022 Savoir-faire Linux Inc. and contributors' ...@@ -22,8 +22,14 @@ copyright = '2018-2022 Savoir-faire Linux Inc. and contributors'
author = 'Savoir-faire Linux Inc. and contributors' author = 'Savoir-faire Linux Inc. and contributors'
extensions = [ extensions = [
'myst_parser'
] ]
source_suffix = {
'.rst': 'restructuredtext',
'.md': 'markdown',
}
templates_path = ['_templates'] templates_path = ['_templates']
exclude_patterns = ['_build'] exclude_patterns = ['_build']
......
guides/how-to-report-bugs.md 0 → 100644
+ 221
− 0
View file @ f76fe280
**Note: We are currently a small number of developers active on the
project. As such, we cannot answer and tag all of the opened issues
immediately, but we do notice and read them. Good bug reports provide
us important feedback, which we thank you for and always appreciate.**
How to report bugs and issues
=============================
Set up your environment
-----------------------
- Be ready for data loss. Back up your account and link your
account to as many devices as possible.
- Install the latest version (or even a beta version) of Jami.
Reporting bugs/issues against older versions is less useful,
and there is a likelihood of it already having been fixed in
newer versions.
How to report a bug
-------------------
0\. Create an account on the [Jami GitLab](https://git.jami.net/users/sign_up)
if you don't have one already.
1\. Choose the right project to post your issue in:
* [The Android client](https://git.jami.net/savoirfairelinux/jami-client-android)
* [The Qt client](https://git.jami.net/savoirfairelinux/jami-client-qt)
* [The GNOME/GTK client](https://git.jami.net/savoirfairelinux/jami-client-gnome)
* [The iOS client](https://git.jami.net/savoirfairelinux/jami-client-ios)
* [The macOS client](https://git.jami.net/savoirfairelinux/jami-client-macos)
* [The Jami project in general (or if you are not sure)](https://git.jami.net/savoirfairelinux/jami-project)
* [If you know what you are doing you may choose one of the other projects](https://git.jami.net)
2\. If you have multiple issues, please file separate bug reports.
It will be much easier to keep track of them that way.
3\. Title is an explicit summary of the bug (e.g.: header bar is too big due to icon size)
4\. Figure out the steps to reproduce the bug:
- If you have precise steps to reproduce it (great!) you're on your
way to creating a helpful bug report.
- If you can reproduce occasionally, but not after following
specific steps, please provide additional information about the
issue to help others understand and try to reproduce it.
- If you can't reproduce the problem, there may be little chance of
it being reasonably fixable. If you do report it, please try your
best to provide as much information/clues about its occurrence as
possible.
5\. Make sure your software is up to date. Ideally, test an
in-development version to see whether your bug has already been fixed.
6\. Try to isolate from environment and reproduce (i.e. test on
multiple devices).
7\. Describe your environment(s) by specifying the following:
- OS version
- precise device model (important for mobile devices)
- if you are using a beta version
- what build you are using (F-Droid, Play Store, App Store, from
dl.jami.net, your own build, etc.). If you have built your own
version of Jami, please specify the exact Jami Daemon version and
client version (you can obtain it using `jamid -v` and
`jami-gnome -v` or `jami-qt -v`; but note that our packages are
updated quite often) and the Git commit.
- network conditions: are both devices on the same local network?
Different networks? Is one or both behind NAT? Are you using LTE?
Are you using WiFi?
- other elements if needed: SIP provider, hardware, etc.
Writing a clear summary
-----------------------
How would you describe the bug using approximately 10 words?
This is the first part of your bug report a developer will see.
A good summary should quickly and uniquely identify a bug report.
It should explain the problem, not your suggested solution.
```
Good: "Cancelling a file transfer crashes Jami"
Bad: "Software crashes"
```
```
Good: "All calls hang up after 32 seconds"
Bad: "Not able to call my friends"
```
Writing precise steps to reproduce
----------------------------------
* How can a developer reproduce the bug on his or her own device?
Steps to reproduce are the most important part of any bug report.
If a developer is able to reproduce the bug, the bug is very likely
to be fixed. If the steps are unclear, it might not even be possible
to know whether the bug has been fixed. We are totally aware that
some bugs may look obvious to you, but they are probably related to
your environment. The more precise you are, the quicker the bug can
be fixed.
* What should you include in a bug report?
Indicate whether you can reproduce the bug at will, occasionally, or
not at all. Describe your method of interacting with Ring in addition
to the intent of each step. After your steps, precisely describe the
observed (actual) result and the expected result. Clearly separate
facts (observations) from speculations.
### Good :
I can always reproduce by following these steps:
```
1. Start Jami by clicking on the desktop icon
2. Start a new conversation with anyone
3. Click the file transfer icon
Expected results: A window opens and ask me to choose a file to send.
Actual results: When I click the file transfer icon, nothing happens.
```
### Bad :
```
Try to transfer a file
It doesn't work.
```
Obtained Result
---------------
Please include:
+ The daemon and client debug logs.
+ The core dump if one was produced.
Expected Result
---------------
It's a description of expected or desired behaviour.
Providing additional information
--------------------------------
The following information is requested for most bug reports. You can
save time by providing this information below the Expected results.
### Logs
#### Qt client (GNU/Linux, Windows)
Go to the General settings. In the Troubleshoot section, you can
click on "Open logs", where you will be able to get statistics ("Show
stats") or start recording information via "Receive logs".
Then you can just copy the result and explain your scenario.
#### On GNU/Linux
Classic logs (by default logs only >= warning are logged):
```
journalctl --since "24h ago" | grep jami
```
Full log:
Since the Jami client (GUI) and daemon are separated processes, the
easiest way to get logs from both is to start them one at a time,
manually.
1. Ensure that no Jami client or daemon instances are running: check
by running `ps aux | grep jami` in a terminal.
+ Jami may still be running even if no windows are open,
depending on your preferences.
+ If either client or daemon are running, terminate them using
`kill PID`.
2. In one terminal, start the daemon with `jamid -d -c`
+ This executable is normally not in the `PATH`, and in the
Debian/Trisquel/Ubuntu packages, it is located at
`/usr/lib/x86_64-linux-gnu/jamid -d -c` or
`/usr/libexec/jamid -d -c`.
3. In another terminal, start the client, using e.g. `jami-gnome -d`
or `jami-qt -d`.
To get a backtrace, you can run the program inside GDB:
`gdb -ex run jami-qt`, or `gdb -ex run jami-gnome`, or
`gdb -ex run --args /usr/libexec/jamid -cd`, depending on the
component you need to debug.
When it crashes, you can type `bt` (or even better,
`thread apply all bt`) then press *Enter*.
Then copy the backtrace and paste it in the issue.
#### On macOS
+ Navigate to `/Applications/Jami.app/Contents/MacOS/`.
+ Double click Jami. It will launch Jami and print the log to the
terminal.
+ Copy log from terminal to a file.
#### On Android
+ You need to have adb setup on your computer.
+ Launch Jami on your smartphone and then execute
+ ```adb logcat *:D | grep `adb shell ps | egrep 'cx.ring' | cut -c10-15` > logring.txt```
+ You now have a file containing the log of the client
#### For Windows
Open a terminal (cmd.exe) and launch Jami.exe with the following
options:
+ `-d` to open a separate console window to receive logs
+ `-f` to write logs to `%localappdata%\jami\jami.log`
+ `-c` to print logs directly to the Visual Studio debug output window
guides/index.rst
+ 1
− 0
View file @ f76fe280
...@@ -9,3 +9,4 @@ These are how-to guides that should `follow this format ...@@ -9,3 +9,4 @@ These are how-to guides that should `follow this format
:maxdepth: 1 :maxdepth: 1
how-to-contribute-to-this-documentation how-to-contribute-to-this-documentation
how-to-report-bugs
tutorials/Bug-report-guide.md deleted 100644 → 0
+ 0
− 189
View file @ e6152a34
**Note: We are currently a few devs active on the project. We can't answer and tags each issues opened, but we read it. A good issue provide an important feedback and thank you for that, any feedback is appreciated.**
Setup your environment
----------------------
- Be ready for data loss. Backup your account and link your account to
as many devices as possible.
- Install the latest version (or even a beta version) of Jami. It is
useless to report bugs on older versions.
How to report a bug
-------------------
0\. Create an account on [our git repository](https://git.jami.net/users/sign_in) (if it is not already done)
1\. Choose the right project to post your issue in:
* [The Android client](https://git.jami.net/savoirfairelinux/ring-client-android)
* [The Windows client](https://git.jami.net/savoirfairelinux/ring-client-windows)
* [The Linux client](https://git.jami.net/savoirfairelinux/ring-client-gnome)
* [The iOS client](https://git.jami.net/savoirfairelinux/ring-client-ios)
* [The macOS client](https://git.jami.net/savoirfairelinux/ring-client-macosx)
* [The Jami project in general (or if you are not sure)](https://git.jami.net/savoirfairelinux/ring-project)
* [If you know what you are doing you may choose one of the other projects](https://git.jami.net/)
2\. If you have multiple issues, please file separate bug reports. It
will be much easier to track bugs that way.
3\. Title is an explicit summary of the bug (e.g.: header bar is too big due to icon size)
4\. Figure out the steps to reproduce the bug:
- If you have precise steps to reproduce it — great! — you're on your
way to creating a useful bug report.
- If you can reproduce occasionally, but not after following specific
steps, you must provide additional information for the bug report to
be useful.
- If you can't reproduce the problem, there's probably no use in
reporting it, unless you provide unique information about
its occurrence.
- If the bug leads to other bugs afterward that you can't reproduce
some other way, there's probably no use in reporting it.
5\. Make sure your software is up to date. Ideally, test an
in-development version to see whether your bug has already been fixed
6\. Try to isolate from environment and reproduce (ie: test on multiple
devices)
7\. Describe your environment(s) by specifying the following:
- OS version
- precise device model (important for mobile devices)
- if you are using a beta version
- what build you are using (from ring.cx, F-droid, Play Store, App store, you own...). If you have built your own version of Ring, please specify the exact dring version (LibRing or Daemon) and client version (You can obtained it with `dring -v` and `jami-gnome -v`. But note that our packages are updated quite often) and the Git commit.
- network conditions: Are both devices on the same local network? Different networks? Is one or both behind NAT? Are you using LTE? Wifi?
- other elements if needed: SIP provider, hardware...
Writing a clear summary
-----------------------
How would you describe the bug using approximately 10 words? This is the
first part of your bug report a developer will see.
A good summary should quickly and uniquely identify a bug report. It
should explain the problem, not your suggested solution.
```
Good: "Cancelling a file transfer crashes Ring"
Bad: "Software crashes"
```
```
Good: "All calls hang up after 32 seconds"
Bad: "Not able to call my friends"
```
Writing precise steps to reproduce
----------------------------------
* How can a developer reproduce the bug on his or her own device?
Steps to reproduce are the most important part of any bug report. If a
developer is able to reproduce the bug, the bug is very likely to be
fixed. If the steps are unclear, it might not even be possible to know
whether the bug has been fixed. We are totally aware that some bugs may
look obvious to you, but they are probably related to your environment.
The more precise you are, the quicker the bug is fixed.
* What should you include in a bug report?
Indicate whether you can reproduce the bug at will, occasionally, or not
at all. Describe your method of interacting with Ring in addition to the
intent of each step. After your steps, precisely describe the observed
(actual) result and the expected result. Clearly separate facts
(observations) from speculations.
### Good :
I can always reproduce by following these steps:
```
1. Start Ring by clicking on the desktop icon
2. Start a new conversation with anyone
3. Click file transfer icon
Expected results: A window opens and ask me to choose a file to send.
Actual results: When I click the file transfer icon, nothing happens.
```
### Bad :
```
Try to transfer a file
It doesn't work.
```
Obtained Result
---------------
Please include:
+ The daemon (or LibRing) and client debug logs.
+ The core dump if one was produced.
Expected Result
---------------
It's a description of expected or desired behaviour.
Providing additional information
--------------------------------
The following information is requested for most bug reports. You can
save time by providing this information below the Expected results.
### Logs
#### Client-qt (Windows, GNU/Linux)
Go to the General settings. In the Troubleshoot section, you can clic on "Open logs", where you will be able to get statistics ("Show stats") or start recording informations via "Receive logs". Then you can just copy the result and explain your scenario.
#### On GNU/Linux
Classic logs (by default logs only >= warning are loggued):
```
journalctl --since "24h ago" | grep jami
```
Full log:
Since the Ring GUI and daemon are separated processes, the easiest way to get logs from both is to start them one at a time, manually.
1. Ensure that no ring client or daemon instances are running with `ps aux | grep jami`
+ Jami may still be running even if no windows are open depending on your preferences.
+ If either client or daemon are running, kill them with `kill PID`
2. On one terminal, start the daemon with `jamid -d -c`
+ This executable is normally not in the PATH, and on the Ubuntu packages, it is located at `/usr/lib/x86_64-linux-gnu/jamid -d -c` or `/usr/libexec/jamid -d -c`
3. In another terminal, start the client with (here is a Gnome example) `jami-gnome -d`
For getting a backtrace, you can run the program inside gdb:
̀ gdb -ex run jami-qt` or ̀ gdb -ex run jami-gnome` or `gdb -ex run --args /usr/libexec/jamid -cd` depending the part you need to debug
When it does crash, you can type `bt` then press **Enter**. And copy the backtrace to the issue. (or `thread apply all bt` is event better)
#### On Mac OS
Navigate to /Applications/Jami.app/Contents/MacOS/
+ Double click Jami. It will launch Jami and print the log to the terminal.
+ Copy log from terminal to a file.
#### On Android
+ You need to have adb setup on your computer.
+ Launch Ring on your smartphone and then execute
+ ```adb logcat *:D | grep `adb shell ps | egrep 'cx.ring' | cut -c10-15` > logring.txt```
+ You now have a file containing the log of the client
#### For Windows
Open a terminal(cmd.exe) and launch Jami.exe with the following options:
+ `-d` to open a separate console window to receive logs
+ `-f` to write logs to `%localappdata%\jami\jami.log`
+ `-c` to print logs directly to the Visual Studio debug output window
\ No newline at end of file
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment