[SCM] Debian Live manual branch, master, updated. 09f0692233dd0250ee0ae6161d3c224cfc23ddc6

[Daniel Baumann]

The following commit has been merged in the master branch:
commit 09f0692233dd0250ee0ae6161d3c224cfc23ddc6
Author: Daniel Baumann <daniel at debian.org>
Date:   Fri May 9 06:54:41 2008 +0200

    Adding bugs.

diff --git a/chapters/bugs.sgml b/chapters/bugs.sgml
new file mode 100644
index 0000000..d2598a6
--- /dev/null
+++ b/chapters/bugs.sgml
@@ -0,0 +1,96 @@
+<chapt id="bugs">
+<heading>How to report a bug in Debian Live</heading>
+
+<p><i>"No software is perfect... we need your help!"</i></p>
+
+<p>Debian Live is far from being perfect, but we want to make it as close as possible to perfect - with your help.</p>
+
+<p>As such, do not hesitate to report a bug: it is better to fill a report twice or even to report a potential non-bug than no bug at all.</p>
+
+<p>However, here are some recommendations how to file good bug reports so that they are the most effective.</p>
+
+<p>For the impatient:</p>
+
+<ul><li>Do always reproduce with the most current version of live-helper and live-initramfs before submitting a bugreport.</li>
+
+<li>Do always try to give as *specific* as possible information about the bug. This not just includes the version of live-helper and live-initramfs used, the distribution of the live system you are building.</li></ul>
+
+<sect>
+<heading>Where does the bug appear?</heading>
+
+<p>...at build time while bootstrapping?</p>
+
+<p>live-helper first bootstraps a basic Debian system with debootstrap(8) or
+cdebootstrap(1). Depending on both debootstrap/cdebootstrap and the Debian
+distribution it is bootstrapping, it runs sucessful or not. If a bug appears
+here, check if the error is related to a specific Debian package (most likely),
+or if it is related to debootstrap/cdebootstrap itself. Running lh_bootstrap
+with --debug gives you more information.</p>
+
+<p>Also, if you are using a local mirror or any of sort of (package) proxy and
+you are experiencing a problem with bootstrapping, always reproduce it first by
+bootstrapping from an official Debian mirror.</p>
+
+<p>In all cases above, these are not a bug in live-helper, but rather in Debian
+itself. We can not fix this directly. Instead, report such a bug against the
+failing package, or in case of a bug in the bootstrapping tool, against
+debootstrap or cdebootstrap, or the (package) proxy software you are using.</p>
+
+<p>...at build time while installing packages?</p>
+
+<p>live-helper installs additional packages from the Debian archive. Depending
+on the Debian distribution used and the daily archive state, it can fail. If a
+bug appears here, check if the error is also reproducible on a normal installed
+(non-live) system.</p>
+
+<p>Also, if you are including any sort of unofficial package to your live system
+and you are experiencing problems, rebuild without those before filling a bug
+to make sure that they are not the cause of the failure.</p>
+
+<p>In all cases above, these are not a bug in live-helper, but rather in Debian
+again. Report it against the failing package(s).</p>
+
+<p>...at boot time?</p>
+
+<p>If your image does not boot, please report it to the mailing list together
+with the information requested in 2. Do not forget to mention, how/when the
+image failed, in qemu, vmware or real hardware. If you are using a
+virtualization technology of any kind, do always run it on real hardware before
+reporting a bug. Nevertheless, providing a screenshot of the failure is also
+very helpful.</p>
+
+<p>...at run time?</p>
+
+<p>If a package was successfully installed, but fails while actually running the
+Live system, this is probably a bug in Debian Live and you are welcome to report
+it to us.</p>
+</sect>
+
+<sect>
+<heading>Where to send the bug report?</heading>
+
+<p>Report error logs of build time errors to live-helper and run time errors to
+live-initramfs in the Debian Bug Tracking System. If you are unsure or need more
+help before submitting a bug report, you can always send a message to
+<debian-devel-live at lists.alioth.debian.org>. We will help you to figure it out.</p>
+
+<p>To make the most out of your bug report, we require at least the following
+information:</p>
+
+<ul><li>Architecture of the host system</li>
+<li>Version of live-helper on the host system</li>
+<li>Version of live-initramfs on the live system</li>
+<li>Version of debootstrap and/or cdebootstrap on the host system</li></ul>
+
+<ul><li>Architecture of the live system</li>
+<li>Distribution of the live system</li>
+<li>Version of the kernel on the live system</li></ul>
+
+<p>Additionally, to rule out other errors, it is always a good idea to tar up
+your config directory and upload it somewhere (do *not* send it as an attachment
+to the mailinglist), so that we can try to reproduce the errors you
+encountered.</p>
+
+</sect>
+
+</chapt>

-- 
Debian Live manual