Add section on reporting bugs to Obnam

1 files changed, 52 insertions, 0 deletions

diff --git a/manual/en/140-troubleshooting.mdwn b/manual/en/140-troubleshooting.mdwn
index 1d4b377b..85a297cc 100644
--- a/manual/en/140-troubleshooting.mdwn
+++ b/manual/en/140-troubleshooting.mdwn
@@ -5,3 +5,55 @@ This chapter discusses how to debug problems with Obnam. It covers
 things such as log files, various levels of logging and tracing, and
 common problems with Obnam use. It also explains what things go where
 in an Obnam backup repository.
+
+
+Reporting problems ("bugs")
+---------------------------
+
+If you have a problem with Obnam, and you want to report it (please
+do!), including the following information is helpful and makes it
+easier to figure out what the problem is.
+
+* You should report problems to the `obnam-support@obnam.org` mailing
+  list. This is a publically archived mailing list where various
+  people help others use Obnam.
+
+* What is the problem? What did you try to achieve? What actually
+  happened?
+
+* The version of Obnam and Larch you're using, and how you installed
+  it.
+    - On Debian, run `dpkg -l obnam python-larch` on the command line
+      and include the output.
+
+* The exact command line you used. Copy-paste it instead of
+  typing it again into the mail. Sometimes the problem can be hidden
+  if you don't copy the command line exactly. Also, copying by typing
+  is boring, and we should avoid boring things in life.
+
+* If there's an error message, copy-paste that into the mail.
+
+* The output of `obnam --dump-config`, which includes the full
+  configuration. Include it as an attachment to your mail to
+  `obnam-support`. If you have some secret information, such as
+  filenames or hostnames, you can replace those with XXXX.
+
+* If you can reproduce the problem while running with
+  `--log-level=debug`, `--log=obnam.log` and `--trace=obnamlib`
+  options, include a suitable amount from the end of the log file. The
+  suitable amount may depend on the situation, but if you give the
+  last two hundred lines, and it's not enough, we'll ask for more.
+  Again, feel free to replace any sensitive filenames, etc, with XXXX.
+
+* The output of the `env` command, in the same terminal window in
+  which you ran Obnam. (Again, as an attachment.)
+
+* If your bug is about performance, please run Obnam under profiling,
+  and attach the profiling file. To run Obnam under profiling, install
+  the Python profile (`python-profiler` package in Debian/Ubuntu), and
+  set the `OBNAM_PROFILE` environment variable to the name of the file
+  with the profiling output (that's the file you should send by mail).
+  For example: `OBNAM_PROFILE=obnam.prof obnam backup` would run the
+  backup under the profiler, and write the result to `obnam.prof`.
+
+Thank you for your help in making Obnam better.