[WIP][RFC] Add a mini-guide for debugging packages and programs, to help with better issue reports

src/SUMMARY.md

@@ -76,4 +76,5 @@
       - [Common Issues](./xbps/troubleshooting/common-issues.md)
       - [Static XBPS](./xbps/troubleshooting/static.md)
 - [Contributing](./contributing/index.md)
-   - [Contributing To void-docs](./contributing/void-docs/index.md)
+   - [Contributing To void-docs](./contributing/void-docs.md)
+   - [Troubleshooting Packages](./contributing/debug.md)

src/contributing/debug.md

@@ -0,0 +1,67 @@
+# Troubleshooting badly behaving apps
+
+Despite the best efforts of Void Linux maintainers, it is possible that you will
+have issues with packages from the official repositories. On such cases, there
+are some steps you can follow in order to provide as complete a bug report as
+possible.
+
+Some of these steps can even help you find the cause of the issue yourself!
+
+## Look at error messages attentively
+
+It is possible the program's output tells you why it errors out, so you can try
+to run it in a terminal. For example:
+
+- Python programs complain loudly about missing modules or resources.
+- If you're using a compiled binary, and it can't find the libraries it depends
+   on, your dynamic linker will tell you about it.
+
+## Check for issues in the package database
+
+You can use the `-a` flag for
+[xbps-pkgdb(1)](https://man.voidlinux.org/xbps-pkgdb.1) to run a complete check
+on all systems packages, which can detect any files that may have been altered
+when they shouldn't have been. You should attempt to reinstall all the packages
+listed in this step, using the `-f` flag for
+[xbps-install(1)](https://man.voidlinux.org/xbps-install.1). For example:
+
+```
+# xbps-pkgdb -a
+ERROR: p7zip: hash mismatch for /usr/bin/7z.
+ERROR: p7zip: files check FAILED.
+# xbps-install -f p7zip
+```
+
+After this is done, you should check if the issue persists.
+
+## Strace the program
+
+If the issue is caused by a program, you can run it under the
+[strace(1)](https://man.voidlinux.org/strace.1) utility to check if it's trying,
+for example, to access files that don't exist but that it expects to exist.
+
+## Debug the program NEEDS WORK
+
+If a look at `strace` wasn't enough, it is possible to use a debugger like
+[gdb(1)](https://man.voidlinux.org/gdb.1) to step through the program's
+execution. You can [install debug packages](../xbps/repositories/index.md) or
+use Void's [Debuginfod](https://sourceware.org/elfutils/Debuginfod.html) server.
+To use the Debuginfod server, you need to export the `DEBUGINFOD_URLS`
+environment variable with a value of `https://debugingod.s.voidlinux.org` or
+`https://debuginfod.elfutils.org/`.
+
+GDB is especially useful when an application crashes abnormally, since it will
+stop execution at that point, and you can gather relevant information there. The
+syntax for using `gdb` is shown below, including the Debuginfod variable:
+
+```
+$ DEBUGINFOD_URLS="https://debugingod.s.voidlinux.org" gdb --args <program> [arguments]
+```
+
+Inside GDB, a usual session will run the following commands:
+
+- `run` to start the application;
+- `set logging on`, to create a `gdb.txt` file which can be shared easily;
+- `backtrace`, to show the function calls made until the application got to that
+   place;
+- `quit`, to close `gdb`.

src/contributing/index.md

@@ -2,13 +2,21 @@
 
 There's more to running a distribution than just writing code.
 
-To contribute to the Void packages repository, start by reading the
+If you fix an issue with a package, the solution can be added to the official
+package repository, and new packages and updates are also welcome! To contribute
+to the Void packages repository, start by reading the
 [CONTRIBUTING](https://github.com/void-linux/void-packages/blob/master/CONTRIBUTING.md)
 document in the void-packages GitHub repository.
 
-To contribute to this Handbook, read
-[CONTRIBUTING](https://github.com/void-linux/void-docs/blob/master/CONTRIBUTING.md)
-in the void-docs repository.
+If you are unable to fix a package yourself, make sure to [open an
+issue](https://github.com/void-linux/void-packages/issues/new) in the
+void-packages repository. This gives the problem visibility, which can greatly
+speed up a fix. Remember to check the existing issues for your problem! There
+are also some [things you can do to assist in finding the problem](./debug.md).
+
+This Handbook doesn't (yet!) contain all the important Void-specific
+information. To contribute to it see the [void-docs specific
+page](./void-docs.md).
 
 If you have any questions, feel free to ask them via IRC in #voidlinux on
 irc.freenode.net, or in [the voidlinux