Reporting a bug\015\012\015\012{{>toc}}\015\012\015\012Writing 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 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.\015\012 \015\012Following information should be in a a good bugreport:\015\012\015\012# Version of subtle and Ruby# Linux/UNIX distribution, version and computer architecture (x86, x86_64)\015\012# Description of the problem in complete, English sentences\015\012# Detailed steps how to reproduce the problem\015\012# Error messages, a backtrace or a screenshot dependent on the problem\015\012# Everything related to the problem, like your config, external scripts etc.\015\012\015\012_When you include error messages or backtraces, make sure to copy the exact, verbatim messages without paraphrasing or reciting from memory._\015\012\015\012h2. Enable logging\015\012\015\012subtle 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:\015\012\015\012

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

\015\012\015\012h2. Debugging messages and levels\015\012\015\012Per 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.\015\012\015\012The 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.\015\012\015\012h2. Create a backtrace\015\012\015\012When 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.\015\012\015\012In case you want to provide a more thorough backtrace and don't shy away from a bit extra work:\015\012\015\012The 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:\015\012\015\012

ulimit -c unlimited

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

gdb\015\012$ gdb subtle corefile\015\012\015\012(gdb) set logging file backtrace.log\015\012(gdb) set logging on\015\012(gdb) bt\015\012(gdb) set logging off\015\012(gdb) quit

\015\012\015\012This will create a file backtrace.log, please make sure to attach it to the ticket.\015\012\015\012h2. File a ticket\015\012\015\012Once you gathered the required informations you are ready to create the ticket here 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.\015\012\015\012h2. Otherwise..\015\012\015\012If you have problems with the whole process, please ask either in #subtle on irc.freenode.org (IRC) or use the forum¶