= How to Submit a Bug Report =

Submitting ''good'' bug reports is very important.

== Before you Submit any bug ==

* If your report is about a crash or a third-party plugin:

 Remember: '''we don't support third-party plugins''', such as those in the Purple Plugin Pack, encryption plugins, etc.  We didn't develop those plugins and can't help you with those issues. ''(A sizable majority of crashes are caused by misbehaving plugins.)''

  1. Make sure your plugins are of the most current version available.

  2. Disable plugins you have loaded (one by one) until you eliminate the source of the crash.  
   *If your crash is a crash on startup, you can try renaming the prefs.xml file in .purple to something such as prefs.xml.old to force a startup without plugins.  Note that this will lose all settings stored there.
   * If you renamed prefs.xml, enable plugins one at a time and try to reproduce the crash.  Unload those plugins that don't cause the crash to aid troubleshooting.  Once you have narrowed the cause down, continue with the instructions.
   * If disabling a specific plugin solves the crash, make sure your plugins are all updated to the most current release.

   * If all plugins are fully up to date (but the issue continues to occur):
    1. Follow the instructions below to get a .RPT file (Windows users), or [wiki:GetABacktrace get a backtrace (other OS users)].
    1. Report the issue '''to the authors of the plugin''', not us.

   * If all plugins are disabled (but the issue continues to occur), follow the steps below.

* If your bug is other than third-party plugin or crash -related (new features, improvements, etc.), follow the steps below.

= Steps for Bug Report Submission =

1. Check that your problem is not related to a third-party plugin or a crash (read above). If your problem is related to a crash (whether or not it's also related to a third-party plugin), you will have to get the proper log (read below).

2. [http://developer.pidgin.im/query Search for existing bug reports], in order not to submit a duplicated one.  (Note that you may wish to remove the default 'Owner is' field, if you are logged in.)

3. [http://developer.pidgin.im/simpleticket Create a new ticket].[[BR]] '''Note: You must be logged in to submit or comment on tickets! '''  To create a login if you do not have one, click the "Register" link on the top right-hand corner of any tracker page.

= What to do if Pidgin crashes =
== Windows Users ==

 * Make sure that you have the "Debug Symbols" for your current Pidgin version.  These are installed via a checkbox in the installer.
  * To check if you have the debug symbols, check if you have a `pidgin-x.y.z-dbgsym` (with `x.y.z` matching your version) directory in your Pidgin installation directory.
 * The next time you run Pidgin and it crashes, the call stack will be dumped to a `pidgin.RPT` file in your [wiki:"Using Pidgin#Whereismy.purpledirectory" `~/.purple` directory].
 * When submitting a bug report, give a detailed description on how to reproduce your bug and attach the most recent crash dump from your `pidgin.RPT`.
   * Note that each new crash dump will '''''append''''' to the file, so if you have several crashes, all the dumps will be present.


The Microsoft Windows `"Error Report"` isn't useful in any way; please '''''do not''''' include it in the bug report.


== All other (non-Windows) OS users ==
[wiki:GetABacktrace Get a backtrace]

= Obtaining a Debug Log =
If asked to obtain a debug log, the following steps will help you do so.

If Pidgin isn't crashing, you can use the Debug Window (`Help->Debug Window`) to obtain the debug log output.

If Pidgin is crashing, you can save the debug output to a file with the following instructions.

== All OS (except Windows) users ==
Open a terminal and start Pidgin as follows:
{{{
pidgin -d 2>&1 > ~/debug.log
}}}

== Windows ==
Open a Command Prompt window and start Pidgin as follows:[[BR]]
(You should replace `C:\Program Files\Pidgin` with the path to which you installed Pidgin if it is different)
{{{
cd "C:\Program Files\Pidgin"
pidgin.exe -d 2>&1 > "%USERPROFILE%\debug.log"
}}}
This will cause the debug output to be saved in a file called `debug.log` in your %USERPROFILE% directory.

=== Preemptive Debug Logging ===
Pidgin just hiccuped, you want to file a ticket but you wish you had saved the debug log don't you? Here is a script to have it made for you all the time. 

Create a `pidgin.bat` file somewhere on your system (your Documents folder is fine) (If you have Pidgin installed to somewhere other than the default location, update `PIDGIN_INST_DIR` to the appropriate value):
{{{
SET ProgramFiles(x86)
IF %ERRORLEVEL% == 0 SET PIDGIN_INST_DIR=%ProgramFiles(x86)%\Pidgin
IF NOT %ERRORLEVEL% == 0 SET PIDGIN_INST_DIR=%ProgramFiles%\Pidgin

REM SET PIDGIN_INST_DIR=Z:\YourCustomPidginInstallationDirectory

SET LOCALAPPDATA
IF %ERRORLEVEL% == 0 SET DEBUG_DIR=%LOCALAPPDATA%\.purple\debuglogs
IF NOT %ERRORLEVEL% == 0 SET DEBUG_DIR=%APPDATA%\.purple\debuglogs

REM make sure the debug directory exists
IF NOT EXIST "%DEBUG_DIR%" mkdir "%DEBUG_DIR%"

REM get the date and time
SET dt=%date%_%time%

REM replace the / with - (may or may not exist depending on your date format)
SET dt=%dt:/=-%

REM replace the ' ' with 0 (may or may not exist depending on your date format)
SET dt=%dt: =0% 

REM replace the : with . (may or may not exist depending on your date format)
SET dt=%dt::=.%

REM build the logfile name
SET logfile=%DEBUG_DIR%\%dt%.log

REM remove the space that gets created for some reason...
SET logfile=%logfile: =%

REM quote logfile
SET logfile="%logfile%"

REM write a nice header
ECHO -------------------------------------------------  > %logfile%
ECHO Pidgin Debug Log For %date% %time%                >> %logfile%
ECHO ------------------------------------------------- >> %logfile%

"%PIDGIN_INST_DIR%\pidgin.exe" -d 2>&1 >> %logfile%

EXIT
}}}

Create a `pidgin.vbs` file in the same directory as `pidgin.bat` was created above:
{{{
Set WshShell = WScript.CreateObject("WScript.Shell")
obj = WshShell.Run("pidgin.bat", 0)
}}}

Create a shortcut to the `pidgin.vbs` file on your Desktop (or wherever is convenient) and use that to launch Pidgin.  You can assign the icon from pidgin.exe to the shortcut to make it look nice.