Where to Report Bugs

The first thing to do is to look at the Pan bug database to see if the bug you're experiencing has already been reported:

• If you can't find the bug listed, go read abisource's bug reporting guidelines and "what to report", then fill out a new bug report.
  
• If the bug is in the open bugs list, you can add a comment at the end of the bug. (Keep reading to learn what information helps us the most.)
  
• If the bug is in the closed bugs list (including the old Bugzilla database), 99% of the time it's because the bug has been fixed in a newer version of Pan. 1% of the time it's because the bug reporter has disappeared and the bug's been marked "NEEDINFO"; feel free to reopen this bug and add your own comment in the form. (Again, keep reading to learn what information helps us the most.)

What to Report

Please read Apache's bug reporting guidelines first,
then make sure your bug report contains:

• The version of Pan you're using (e.g., 0.141)
• A description of the problem.
• Always include a backtrace and/or runlog for crashes, freeze-ups, and runaway programs.
• If the problem is reproducible, always include a recipe for us to follow.
• Anything else you think could be important. Too much information is better than not enough.

Runlogs

Runlogs should almost always be included with a bug report. If Pan is crashing, providing this and a backtrace together is extremely helpful. If Pan isn't working with your news server, a runlog will show the dialog that Pan and your server are having. Best of all a runlog requires no special tools; all you need is to start Pan with the command-line argument --debug.

Backtraces

In cases of crashes, freeze-ups, or runaway programs, a backtrace is often a roadmap to the bug.

Because of differences in operating systems, news servers, and other variables, it's at best tedious or at worst impossible to reproduce some of the problems reported to us. With tools that come installed on most Unix/Linux systems, though, you can make a roadmap for us in just a couple of minutes.

If Pan crashes for you, you can get a backtrace by hand fairly easily. Here is a walk-through of the entire process, including the commands you type and a running explanation.

% uname -a (system information)
Linux localhost 1.2.3
% gdb pan (Start gdb.)
(gdb) handle SIGUSR1 nostop noprint (Threads)
(gdb) handle SIG32 nostop noprint
(If you get a `SIG32 not recognized' error, just ignore it and keep going.)
(gdb) run (Start pan)
(At this point, use Pan until it freezes up or crashes.
If Pan freezes, you'll have to type CTRL-C to get the gdb prompt.)
Program received signal SIGINT, Interrupt.
(gdb) thread apply all bt (Show backtraces for every thread)
Thread 7 (LWP      7        ):
#0  0x404b76a0 in poll ()
#1  0x4040d2db in __pthread_manager ()

Thread 6 (LWP      6        ):
#0  0x4044167a in sigsuspend ()
#1  0x40410703 in __pthread_lock ()
#2  0x4040e06a in pthread_mutex_lock ()

Thread 5 (LWP      5        ):
#0  0x404b8cfe in select ()

Thread 4 (LWP      4        ):
#0  0x404b8cfe in select ()
#1  0x40351b98 in _XlcPublicMethods ()

Thread 3 (LWP      3        ):
#0  0x4044167a in sigsuspend ()

Thread 2 (LWP      2        ):
#0  0x4044167a in sigsuspend ()
#1  0x4040c81c in pthread_cond_wait ()

Thread 1 (LWP      1        ):
#0  0x404b8cfe in socket_connect ()
#1  0x40351b98 in nntp_handshake ()
#2  0x40351b44 in download_new_headers ()
(gdb) quit (Quits gdb)
% (attach the terminal output to your email or paste it in a bug report)