Reporting a bug¶

• Table of contents
• Reporting a bug
  • Enable logging
  • Debugging messages and levels
  • Create a backtrace
  • File a ticket
  • Otherwise..

Writing a good bugreport is easy, requires only a few steps and makes it easier to understand the actual problem. Before you consider to write a bug report, please make sure you are using the latest version of subtle and check, if there is a similar ticket in the bugtracker.

If there is such a ticket, it's always good to attach your problem description to the ticket as well. This will automatically add you to the watchers list and you are informed on changes of the ticket.

Following information should be in a a good bugreport:

1. Version of subtle and Ruby
2. Linux/UNIX distribution, version and computer architecture (x86, x86_64)
3. Description of the problem in complete, English sentences
4. Detailed steps how to reproduce the problem
5. Error messages, a backtrace or a screenshot dependent on the problem
6. Everything related to the problem, like your config, external scripts etc.

When you include error messages or backtraces, make sure to copy the exact, verbatim messages without paraphrasing or reciting from memory.

Enable logging¶

subtle writes messages and errors either to stdout or stderr and there is no own facility to write log files. This can be troublesome whenever a login manager is involved or other programs post messages there too. The easiest way to create a real logfile is to redirect the output to a file from your ~/.xinitrc:

exec subtle &> $HOME/subtle-$(date +"%F-%H-%M").log

Debugging messages and levels¶

Per default, subtle is compiled without debugging symbols and messages and needs to be recompiled in order to enable this. Please refer to the install docs how to compile subtle manually with debugging support.

The debugging output is grouped into several levels and the amount of output varies. When no level is used, every debugging message will be visible. The various levels with a description can be found here.

Create a backtrace¶

When execinfo.h is present on your system, subtle will print the last 10 stack frames. This information is barely useful without debugging support but still better than no output. Please make sure to include it in your bugreport as well.

In case you want to provide a more thorough backtrace and don't shy away from a bit extra work:

The kernel can be advised to create a core file (core dump) on a crash, if the line with the segmentation fault contains '(cored dumped)' your system is already set up. Otherwise you need to set the limits for this:

ulimit -c unlimited

Once you get a core file you need to open it with gdb like this:

gdb
$ gdb subtle corefile

(gdb) set logging file backtrace.log
(gdb) set logging on
(gdb) bt
(gdb) set logging off
(gdb) quit

This will create a file backtrace.log, please make sure to attach it to the ticket.

File a ticket¶

Once you gathered the required informations you are ready to create the ticket here.

Whenever the status of the ticket changes you will get a mail, the usual changes are confirmed (when the problem is known or reproducible), fixed or rejected.

Otherwise..¶

If you have problems with the whole process, please ask either in #subtle on irc.freenode.org (IRC) or use the forum.