Bug Reporting Guidelines

Jiří Janoušek edited this page May 2, 2018 · 28 revisions

Bug reporting is a dialog between an user who experiences an issue with Nuvola Apps and the developer who tries to identify the cause of the issue in order to fix it.

Before Reporting New Issue

  • Use genuine builds: Nuvola Apps team has limited resources and provides support only to users of the genuine flatpak builds of Nuvola. If you use a third-party build, contact your distributor to get help.
  • Use the latest release: Run flatpak update --system; flatpak update --user to make sure all your Nuvola packages are up-to-date.
  • Check for duplicates: Please take a look at a list of recently updated issues.

How to report a bug

  1. Register a GitHub account unless you already have one.
  2. Create a new issue in the Nuvola Apps Runtime issue tracker.
  3. Choose a short, but descriptive title (one or two sentences):
    • Bad: "Dialog crashes." What dialog? When is it happening?
    • Good: "Nuvola crashes when Preferences dialog is opened."
    • Bad: "Rdio doesn't work." What exactly doesn't work? What was your expectation?
    • Good: "Radio does not respond to toolbar actions (play/pause)"
    • Bad: "Media keys support" What's wrong with the media keys support?
    • Good: "Nuvola doesn't respond to media keys when Google Chrome is running"
    • Bad: "It doesn't work" Honestly, are you kidding me?
    • Good: "Nuvola doesn't launch after upgrade to version 1.2.3"
  4. Add basic information about your system, Nuvola version and logs (see bellow).
  5. Respond to additional questions from the developer. Your bug report might be closed otherwise.

Basic Information

All bug reports should contain following basic information. You have to be familiar with a terminal (command line window) in order to continue.

Your System

  1. Your Linux distribution and its version, e.g. "Ubuntu 14.04".
    • You can use commands lsb_release -a or cat /etc/issue /etc/*release to obtain this information.
  2. Architecture of your system, e.g. "i686", "x86_64".
    • You can use a command uname -m to obtain this information.
  3. Desktop environment you use.
    • e.g. Unity (default in Ubuntu), GNOME (default in Fedora or Ubuntu GNOME), XFCE (default in Xubuntu), KDE (default in Kubuntu), Pantheon (default in elementaryOS), ...

Your Nuvola Version

Specify precise version of Nuvola Apps Runtime, e.g. "Nuvola Apps 4.9.149", and the script you use, e.g. "Google Play Music 5.0".

  • You can find this information in the About dialog (Menu → About).
  • You can use a command flatpak run eu.tiliado.NuvolaAppXXX --version to obtain this information. Replace NuvolaAppXXX with the real application id, e.g. NuvolaAppDeezer. If you don't know the app id, type NuvolaApp and then the Tab key twice to list available options.

Steps to Reproduce the Issue

Precisely describe

  1. what steps you performed
  2. what happened
  3. what you expected

Debugging Output

  1. Start Nuvola with enabled logging:

    • Run flatpak run eu.tiliado.NuvolaAppXXX --debug in the second terminal window.
    • Replace NuvolaAppXXX with the real application id, e.g. NuvolaAppDeezer. If you don't know the app id, type NuvolaApp and then the Tab key twice to list available options.
  2. If there is a line "Nuvola Apps instance is already running and will be activated", close all Nuvola Apps instances and return to the step 1.

  3. Perform all steps that leads to your issue.

  4. Quit Nuvola.

  5. Copy the complete output from terminal, save it as a text file (*.txt) and attach it to the bug report. github_attach

    • Never trim the logs or you will be asked to provide new complete logs.
    • Don't use "pastebin" services as the logs there may disappear anytime.
    • Don't attach screenshots of the terminal output. Use text files.

Extra information

Please provide this information only if you are asked to do so.

WebKitGtk MiniBrowser

You may be asked to try to reproduce the issue in WebKitGtk MiniBrowser. In that case, run following command (in Debian/Ubuntu), type address of your streaming service and check whether the issue is reproducible.

  • /usr/lib/x86_64-linux-gnu/webkit2gtk-4.0/MiniBrowser (64bit system)
  • /usr/lib/i386-linux-gnu/webkit2gtk-4.0/MiniBrowser (32bit system)

Memory usage

Post output of the following command:

top -n 1 -p `pidof nuvolaplayer3` -p `pidof apprunner` \ 
-p `pidof WebKitWebProcess` -p `pidof WebKitPluginProcess2`

Get Backtrace

If Nuvola Player crashes with SIGSEGV (segmentation fault), it is necessary to obtain a backtrace (traceback).

  1. In Ubuntu/Debian, install gdb and debugging symbols: sudo apt-get install gdb libgtk-3-0-dbg libglib2.0-0-dbg nuvolaplayer3-dbg.

  2. Then open terminal and run command gdb --args nuvolaplayer3 -D, wait for a prompt (gdb) and type run<Enter>.

  3. Wait for Nuvola Player's start-up as it may take a few minutes depending on how many debugging symbol packages are installed.

  4. Reproduce your crash. You should see a message similar to "Program received signal SEGFAULT, Segmentation fault." and the (gdb) prompt.

  5. Type bt<Enter> to obtain the backtrace.

  6. Type quit<Enter> and then y to quit gdb.

  7. Copy the whole log. It should look like:

fenryxo@growlithe:~$ gdb --args nuvolaplayer3 -D
GNU gdb (Debian 7.7.1+dfsg-5) 7.7.1
Copyright (C) 2014 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.  Type "show copying"
and "show warranty" for details.
This GDB was configured as "x86_64-linux-gnu".
Type "show configuration" for configuration details.
For bug reporting instructions, please see:
<http://www.gnu.org/software/gdb/bugs/>.
Find the GDB manual and other documentation resources online at:
<http://www.gnu.org/software/gdb/documentation/>.
For help, type "help".
Type "apropos word" to search for commands related to "word"...
Reading symbols from nuvolaplayer3...Reading symbols from /usr/lib/debug//usr/bin/nuvolaplayer3...done.
done.
(gdb) run
Starting program: /usr/bin/nuvolaplayer3 -D
[Thread debugging using libthread_db enabled]
Using host libthread_db library "/lib/x86_64-linux-gnu/libthread_db.so.1".

Program received signal SEGFAULT, Segmentation fault.
g_logv (log_domain=0x5555555561d8 "Nuvola", log_level=G_LOG_LEVEL_ERROR, format=<optimized out>, args=args@entry=0x7fffffffde40) at /tmp/buildd/glib2.0-2.42.1/./glib/gmessages.c:1046
1046	/tmp/buildd/glib2.0-2.42.1/./glib/gmessages.c: No such file or directory.
(gdb) bt
#0  g_logv (log_domain=0x5555555561d8 "Nuvola", log_level=G_LOG_LEVEL_ERROR, format=<optimized out>, args=args@entry=0x7fffffffde40) at /tmp/buildd/glib2.0-2.42.1/./glib/gmessages.c:1046
#1  0x00007ffff73eef6f in g_log (log_domain=<optimized out>, log_level=<optimized out>, format=<optimized out>) at /tmp/buildd/glib2.0-2.42.1/./glib/gmessages.c:1079
#2  0x0000555555555fe8 in nuvola_main (args=0x7fffffffe088, args_length1=1) at src/master/master.c:347
#3  0x00007ffff6840b45 in __libc_start_main (main=0x555555555770 <main>, argc=2, argv=0x7fffffffe088, init=<optimized out>, fini=<optimized out>, rtld_fini=<optimized out>, stack_end=0x7fffffffe078) at libc-start.c:287
#4  0x00005555555557a5 in _start ()
(gdb) quit
A debugging session is active.

	Inferior 1 [process 27555] will be killed.

Quit anyway? (y or n) y

Backtrace for Frozen WebKitWebProcess

These instructions are for the Deezer web app. You need to replace Deezer's identifier with the identifier of your particular script.

  1. Find out the name of Nuvola's flatpak remote. For example, it's nuvola in the following example. it may be also eu.tiliado.Nuvola-origin. This name is referenced to as NUVOLA_REMOTE from now on.

    $ flatpak remote-list
    flathub system            
    gnome   system            
    nuvola  system
    
  2. Install debugging symbols for your web app script. The Deezer's one are called eu.tiliado.NuvolaAppDeezer.Debug, the template is eu.tiliado.NuvolaAppXxxx.Debug. If you press the Tab key twice after eu.tiliado.NuvolaApp, shell should provide you with hints.

    $ sudo flatpak install NUVOLA_REMOTE eu.tiliado.NuvolaApp<TAB><TAB>
    eu.tiliado.NuvolaApp8tracks            eu.tiliado.NuvolaAppKexp.Debug
    eu.tiliado.NuvolaApp8tracks.Debug      eu.tiliado.NuvolaAppLogitechMediaServer
    eu.tiliado.NuvolaAppAmazonCloudPlayer  eu.tiliado.NuvolaAppLogitechMediaServer.Debug
    ...
    $ sudo flatpak install NUVOLA_REMOTE eu.tiliado.NuvolaAppDeezer.Debug//stable
    
  3. Install GNOME SDK

    $ sudo flatpak install gnome org.gnome.Sdk//3.24
    $ sudo flatpak install gnome org.gnome.Sdk.Debug//3.24
    
  4. Create a temporary directory nuvolatmp in your home directory.

    $ mkdir ~/nuvolatmp
    
  5. Change coredump pattern:

    $ sudo sysctl kernel.core_pattern=core
    
  6. Enter the temporary directory and launch bash inside the environment of a web app script.

    $ cd ~/nuvolatmp; flatpak run -d --command=bash --filesystem=~/nuvolatmp eu.tiliado.NuvolaAppDeezer
    
  7. Enable unlimited core dump.

    $ ulimit -c unlimited
    
  8. Launch the web app script with --debug parameter, output redirection and background execution.

    $ nuvola-app-<TAB>
    $ nuvola-app-deezer --debug > log.txt 2>&1 &
    
  9. When you are sure that the WebKitWebProcess (the web page) is frozen, abort it.

    $ pkill -SIGABRT WebKitWebProces
    
  10. There should be two files: core and log.txt.

    $ ls
    core  log.txt
    [1]+  Done                    nuvola-app-deezer --debug > log.txt 2>&1
    
  11. The core is probably too large to attach it on GitHub. Let's get backtrace from it - run gdb -c core /app/libexec/webkit2gtk-4.0/WebKitWebProcess, then wait a bit, type bt<Enter>, copy backtrace to a file and finally type quit<ENter>exit<Enter>.

bash-4.3$ gdb -c core /app/libexec/webkit2gtk-4.0/WebKitWebProcess 
GNU gdb (GDB) 7.11.1
Copyright (C) 2016 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.  Type "show copying"
and "show warranty" for details.
This GDB was configured as "x86_64-unknown-linux".
Type "show configuration" for configuration details.
For bug reporting instructions, please see:
<http://www.gnu.org/software/gdb/bugs/>.
Find the GDB manual and other documentation resources online at:
<http://www.gnu.org/software/gdb/documentation/>.
For help, type "help".
Type "apropos word" to search for commands related to "word"...
Reading symbols from /app/libexec/webkit2gtk-4.0/WebKitWebProcess...Reading symbols from /usr/lib/debug//app/libexec/webkit2gtk-4.0/WebKitWebProcess.debug...done.
done.

warning: core file may not match specified executable file.
[New LWP 19]
[New LWP 28]
[New LWP 144]
[New LWP 176]
[New LWP 33]
[New LWP 145]
[New LWP 215]
[New LWP 36]
[New LWP 37]
[New LWP 30]
[New LWP 38]
[New LWP 168]
[New LWP 39]
[New LWP 40]
[New LWP 48]
[New LWP 216]
[New LWP 135]
[New LWP 154]

warning: Could not load shared library symbols for linux-vdso.so.1.
Do you need "set solib-search-path" or "set sysroot"?
[Thread debugging using libthread_db enabled]
Using host libthread_db library "/lib/libthread_db.so.1".
Core was generated by `/app/libexec/webkit2gtk-4.0/WebKitWebProcess 28'.
Program terminated with signal SIGABRT, Aborted.
#0  0x0000003cd00df56d in poll () at ../sysdeps/unix/syscall-template.S:84
84	T_PSEUDO (SYSCALL_SYMBOL, SYSCALL_NAME, SYSCALL_NARGS)
[Current thread is 1 (Thread 0x7f45d165bd80 (LWP 19))]
(gdb) bt
#0  0x0000003cd00df56d in poll () at ../sysdeps/unix/syscall-template.S:84
#1  0x00007f45d974ea16 in g_main_context_poll (priority=<optimized out>, n_fds=6, fds=0x1faee00, 
    timeout=<optimized out>, context=0x1a40720) at gmain.c:4259
#2  g_main_context_iterate (context=0x1a40720, block=block@entry=1, dispatch=dispatch@entry=1, 
    self=<optimized out>) at gmain.c:3955
#3  0x00007f45d974eda2 in g_main_loop_run (loop=0x1b5d310) at gmain.c:4156
#4  0x00007f45df7dc6a0 in WTF::RunLoop::run ()
    at /run/build/webkitgtk4/Source/WTF/wtf/glib/RunLoopGLib.cpp:94
#5  0x00007f45e1e43659 in WebKit::ChildProcessMain<WebKit::WebProcess, WebKit::WebProcessMain> ()
    at /run/build/webkitgtk4/Source/WebKit2/Shared/unix/ChildProcessMain.h:61
#6  0x0000003cd0020291 in __libc_start_main (main=0x400ae0 <main()>, argc=2, argv=0x7fffb7ed91a8, 
    init=<optimized out>, fini=<optimized out>, rtld_fini=<optimized out>, stack_end=0x7fffb7ed9198)
    at /usr/src/debug/glibc/2.24-r0/git/csu/libc-start.c:289
#7  0x0000000000400b3a in _start () at ../sysdeps/x86_64/start.S:120
(gdb) quit
bash-4.3$ exit
exit

Troubleshooting

  • Try to upgrade WebKitGTK+.
  • Use Adwaita theme.
  • WEBKIT_DISABLE_COMPOSITING_MODE=1
  • Advanced backtrace
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.