pidgin/nest

153d57959204
Parents bfceef396691
Children a6832f539981
Add how to submit a bug report and debugging sections

Tackling both of these at once since they are related (a lot of the times to
submit a good bug report you need to provide a debug log or crash dump).

The contents of these sections are heavily based off the content of the old
wiki pages, primarly TipsForBugReports and GetABacktrace.

Testing Done:
Ran `dev-server.sh` and verified contents look as intended.

Reviewed at https://reviews.imfreedom.org/r/802/
--- a/hugo/config.toml Fri Jul 09 23:35:35 2021 -0500
+++ b/hugo/config.toml Mon Jul 12 18:35:43 2021 -0500
@@ -13,6 +13,7 @@
disableShortcutsTitle = true
contributeGuideURL = "https://docs.pidgin.im/libpurple/latest/chapter-code-contributions.html"
+pidginIssuesURL = "https://issues.imfreedom.org/issues/PIDGIN?u=1"
# These enable Open Graph and Twitter cards
description = "Pidgin is a universal chat client, allowing you to consolidate all your different messaging apps into a single tool."
--- a/hugo/content/about/security/_index.md Fri Jul 09 23:35:35 2021 -0500
+++ b/hugo/content/about/security/_index.md Mon Jul 12 18:35:43 2021 -0500
@@ -39,8 +39,8 @@
invalid memory location."
* Steps to reproduce the problem, if known.
* Any debugging information, including backtraces (see our instructions for
- [obtaining a backtrace](https://developer.pidgin.im/wiki/GetABacktrace), a
- debug log (the output of pidgin -d), etc.
+ [obtaining a backtrace]({{< ref "development/debugging#obtaining-a-backtrace" >}}),
+ a debug log (the output of `pidgin --debug`), etc.
* Any proof of concept exploits, debugging tools, or other information you have
and are willing to divulge.
* The oldest and newest versions of our software affected by the bug *to the
--- a/hugo/content/development/contributing.md Fri Jul 09 23:35:35 2021 -0500
+++ b/hugo/content/development/contributing.md Mon Jul 12 18:35:43 2021 -0500
@@ -38,6 +38,74 @@
* Participate in design discussions.
* Add cool features!
+## How to submit a bug report
+
+Submitting *good* bug reports is very important.
+
+### Before you submit any bug report
+
+Remember that **we don't support third-party plugins** like the ones we showcase
+in the [plugins]({{< ref "plugins" >}}) section of this site. We didn't develop
+those plugins and can't help you with those issues. Keep in mind that a sizable
+majority of crashes are caused by misbehaving plugins so the first thing to
+check when an issue appears is whether the issue is caused by a plugin or not.
+
+1. Make sure your plugins are in the most current version available.
+1. Disable plugins you have loaded (one by one) until you eliminate the source
+ of the crash.
+
+ If your crash happens on startup of the application, you can try renaming the
+ `prefs.xml` file in the `.purple` directory to something such as
+ `prefs.xml.old` to force a startup without plugins. Note that this means that
+ you will lose all settings stored there.
+
+1. By now you should know whether the crash is caused by a plugin (ie only
+ happens when a specific plugin is enabled) or if it's an issue in Pidgin
+ itself.
+
+ 1. If the issue is caused by a third party plugin, **report the issue to the
+ authors of the plugin**. Usually the authors specify how to submit issues
+ in the repository where the code of the plugin is hosted.
+ 1. If the issue is caused by a plugin that comes built in to Pidgin or
+ happens with all plugins disabled then follow the instructions below to
+ submit a bug report to the Pidgin project.
+
+### Steps for bug report submission
+
+1. Ensure that you have read the [Before you submit any bug report]({{< ref
+ "#before-you-submit-any-bug-report" >}}) section. This will save you and the
+ Pidgin developers time.
+1. Search our [issue tracking platform]({{< param "pidginIssuesURL" >}}) for
+ existing bug reports that match the issue you have encountered. This is to
+ ensure that we are not submitting a duplicate issue.
+1. If the bug you are reporting is a previously unknown security vulnerability,
+ please read our (Security page)[{{< ref "about/security" >}}] for details on
+ how to submit a security vulnerability report. It's of utmost importance that
+ security issues are not made public until we have the chance to fix them,
+ otherwise our users will be vulnerable until we are able to fix the issue and
+ release a new version of Pidgin.
+1. If you checked all the steps we mentioned before, then go ahead and create
+ the issue in our [issue tracking platform]({{< param "pidginIssuesURL" >}}).
+
+ 1. You need to be logged in to our issue tracker in order to submit issues.
+
+ If you don't already have an account, click on the Login button and from
+ there you'll have the option to either use use one of the social logins
+ available or create a new account directly in our [Jetbrains
+ Hub](https://hub.imfreedom.org) instance, which is the platform we use to
+ handle authentication.
+
+ 1. Ensure you are logged in with your account in our [issue tracking
+ platform]({{< param "pidginIssuesURL" >}}).
+ 1. Submit the bug report, take your time to describe the issue with as much
+ depth as possible and if you can it would also be important to provide the
+ steps needed to reproduce the issue. Another useful section that you may
+ want to checkout, particularly if the issue is about a crash in the
+ application itself, is the [Debugging Pidgin]({{< ref
+ "development/debugging" >}}) one since over there it's explained how to
+ obtain a debug log or a crash dump which will help Pidgin developers a lot
+ when looking at how to fix an issue.
+
## How to contribute code
We acknowledge that Pidgin leverages tools that a lot of developers may not be
@@ -47,8 +115,8 @@
1. Checkout the [version control page]({{< ref version-control >}}). Pay special
attention to the branches which host the Pidgin 3 codebase vs the Pidgin 2
one.
-2. [Using Pidgin mercurial](https://docs.pidgin.im/libpurple/latest/chapter-using-mercurial.html)
-3. [Pidgin code contribution process]({{< param "contributeGuideURL" >}})
+1. [Using Pidgin mercurial](https://docs.pidgin.im/libpurple/latest/chapter-using-mercurial.html).
+1. [Pidgin code contribution process]({{< param "contributeGuideURL" >}}).
If you have any questions about this process, remember that you have a variety
of [methods to reach out to us]({{< ref contact >}}).
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/hugo/content/development/debugging.md Mon Jul 12 18:35:43 2021 -0500
@@ -0,0 +1,198 @@
+---
+title: Debugging
+date: 2021-07-10T09:04:12.000Z
+anchor: debugging
+replaces:
+ - developer.pidgin.im/wiki/GetABacktrace
+ - developer.pidgin.im/wiki/TipsForBugReports
+lastmod: 2021-07-11T19:04:12.000Z
+---
+
+Issues in Pidgin are sometimes hard to troubleshoot so it's of key importance to
+understand how to obtain the necessary information so that developers can
+understand what causes the issue. In this section, we'll explain the two methods
+that are usually followed when troubleshooting issues in Pidgin.
+
+If you are reading this because you are facing an issue and want to submit a bug
+report, make sure you read the [related page]({{< ref
+"development/contributing#submitting-a-bug-report" >}}) before doing so.
+
+## Obtaining a debug log
+
+Debug logs contain messages generated by Pidgin and can help understand what was
+the application doing before a specific event (most likely a bug) got triggered.
+
+Debug logs can be obtained through the Pidgin user interface by opening the
+Debug Window (Help -> Debug Window). However, if Pidgin is crashing and you
+cannot get the debug logs from there, read the following instructions according
+to the operating system you are using to get the debug logs outputted into a
+file.
+
+### All OS except Windows
+
+Open a terminal and start Pidgin as follows:
+
+ ```
+pidgin --debug |& tee ~/debug.log
+```
+
+This will save the debug logs generated by Pidgin in a `debug.log` file that
+will be placed in the home directory of the user executing the command.
+
+## Windows
+
+Open a Command Prompt window and start Pidgin as follows:
+
+```
+cd "C:\Program Files (x86)\Pidgin"
+pidgin.exe --debug 2>&1 > "%USERPROFILE%\debug.log"
+```
+
+**Note:** `C:\Program Files (x86)\` is the default path where Pidgin will be installed
+to, if you installed Pidgin to a different directy make sure you use it when
+running the commands expressed above.
+
+This will save the debug logs generated by Pidgin in a file called `debug.log`
+that will be placed in the `%USERPROFILE%` directory, which normally evaluates
+to `C:\Users\username`.
+
+## Obtaining a backtrace
+
+If Pidgin or Finch has crashed, one of the first things you'll want to do before
+submitting a bug is getting a backtrace. Useful backtraces will help Pidgin
+developers find where in Pidgin, Finch, or LibPurple the bug got triggered and
+from there think about how to find a fix for it.
+
+### All OS except Windows
+
+#### Prerequisites
+
+The most important prerequisite before being able to get a backtrace is to make
+sure that you have the debugging symbols for pidgin, libpurple and finch
+installed.
+
+Please follow the instructions below if you are using one of these distributions
+for more details on how to achieve this. If you are using a different
+distribution then we recommend you to look for a similar page in the
+documentation or find out what packages/configuration is needed before you can
+get useful backtraces.
+
+- Ubuntu: see the [Ubuntu wiki page](https://wiki.ubuntu.com/Backtrace) on
+ obtaining backtraces.
+- Debian: see the [Debian wiki page](http://wiki.debian.org/HowToGetABacktrace)
+ on obtaining backtraces.
+- Fedora: Install the `-debuginfo` rpm first. See [these
+ instructions](http://fedoraproject.org/wiki/StackTraces) for more details.
+- Red Hat Enterprise Linux: Install the `-debuginfo` rpm first, then follow our
+ instructions below.
+- Gentoo: emerge pidgin with`USE=debug`. See the [gentoo wiki
+ page](https://wiki.gentoo.org/wiki/Project:Quality_Assurance/Backtraces) for
+ more details.
+- Arch Linux: see the [Arch wiki
+ page](http://wiki.archlinux.org/index.php/Debug_-_Getting_Traces) on obtaining
+ backgraces, build the debug version of Pidgin and follow the instructions
+ below.
+
+#### Getting traces
+
+The easiest way to obtain a backtrace for Pidgin is by running with gdb. If you
+are trying to get a trace for Finch, then make sure you read [GDB and finch]({{<
+ref "#gdb-and-finch" >}}). Here are the basics:
+
+1. Run the application with gdb and specify to save the output to a file:
+
+```
+$ gdb --args pidgin --debug |& tee ~/pidgin-backtrace.log
+```
+
+1. Next, you'll see some information from gdb similar to this:
+
+```
+GNU gdb Red Hat Linux (5.3post-0.20021129.18rh)
+Copyright 2003 Free Software Foundation, Inc.
+GDB is free software, covered by the GNU General Public License, and you are
+welcome to change it and/or distribute copies of it under certain conditions.
+Type "show copying" to see the conditions.
+There is absolutely no warranty for GDB. Type "show warranty" for details.
+This GDB was configured as "i386-redhat-linux-gnu"...
+(no debugging symbols found)...
+```
+
+1. Start the application from withing the debugger by executing the following
+ commands:
+
+```
+(gdb) handle SIGPIPE nostop noprint
+(gdb) run
+```
+
+1. Information will pass by now and Pidgin will start. You should reproduce your
+ crash now, and once the crash has happened do the following:
+
+```
+(gdb) bt full
+```
+
+When you get the backtrace, instead of seeing function names, you might see '??'
+instead. If that's the case, gdb couldn't read the function names from Pidgin
+and so the backtrace won't end up being very useful after all. These means that
+you are not meeting the [prerequisites]({{< ref "#prerequisites" >}}) stated at
+the begining of this section. If you see function names, then the backtrace is
+good and can be attached to your bug report.
+
+1. Look for the `~/pidgin-backtrace.log` file where the contents of the
+ backtrace should have been saved and attach it to your bug report.
+
+#### GDB and finch
+
+If you are trying to obtain a backtrace for Finch you need to do something
+different as Finch is a console-based application. Assuming that finch will at
+least start up without crashing, you can attach gdb to a running finch process
+from a second terminal in order to debug it. Thus, instead of doing as you would
+with Pidgin (`gdb finch` and then `run`), you will do the following:
+
+1. Start finch as you normally would in a terminal.
+1. Once finch is up and running, open a second terminal and find its process ID
+ using, e.g., the `ps` or the `pidof` commands.
+1. Once you have its process ID (also known as *pid*), run in the second
+ terminal:
+
+```
+$ gdb finch <pid>
+```
+
+1. The finch process will become unresponsive, this is expected. Now similar to
+ before, run:
+
+```
+(gdb) handle SIGPIPE nostop noprint
+(gdb) continue
+```
+
+ Note the use of `continue` instead of `run`. From here on out, to get the
+ backtrace follow the same instructions for Pidgin after the `run` command was
+ executed.
+
+### Windows
+
+- Make sure that you have the "Debug Symbols" for your current Pidgin version.
+ These are installed by selecting a checkbox in the Pidgin installer. You can
+ verify if you have the debug symbols by checking if you have a
+ `pidgin-x.y.z-dbgsym` (with x.y.z matching the Pidgin version you have
+ installed) 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 `%PURPLEHOME%\.purple` directory. Unless you
+ changed it, the default value of `%PURPLEHOME%` matches `%APPDATA%` so in most
+ cases you want to look for the `C:\Users\username\AppData\Roaming\.purple`
+ directory.
+- When [submitting a bug report]({{< ref
+ "development/contributing#how-to-submit-a-bug-report" >}}) remember to attach
+ the most recent crash dump from the aforementioned `pidgin.RPT` file.
+
+ **Note:** Each new crash dump will *append* to the `pidgin.RPT` file, so if
+ you have several crashes all the dumps will be present. Thus, it may be a good
+ idea to delete the file, trigger the crash in Pidgin and then upload that
+ clean `pidgin.RPT` file to the bug report you are submitting.
+
+- The Microsoft Windows "Error Report" isn't useful to us in any way; make sure
+ you **do not** include it in the bug report.
--- a/hugo/content/development/voice-and-video/_index.md Fri Jul 09 23:35:35 2021 -0500
+++ b/hugo/content/development/voice-and-video/_index.md Mon Jul 12 18:35:43 2021 -0500
@@ -49,7 +49,9 @@
### Building with Voice and Video
Please be familiar with compiling and installing code from source. Please also
-submit any bugs you find to Trac ([TipsForBugReports](/wiki/TipsForBugReports)).
+submit any bugs you find to our issue tracking platform, checkout our
+[Contributing page]({{< ref
+"development/contributing#how-to-submit-a-bug-report" >}}) for more details.
Make sure you are using the latest release of Pidgin.