[SCM] Debian Live manual branch, master, updated. 309a564354aa809cf40a0d228ba5105020b9a134

Sun May 11 21:47:55 UTC 2008

The following commit has been merged in the master branch:
commit 204bd0c357794a21a90487b77abbed4726b42ea7
Author: Chris Lamb <chris at chris-lamb.co.uk>
Date:   Sun May 11 22:47:30 2008 +0100

    Merge Daniel's bugs.xml into reporting-bugs.xml
    
    Signed-off-by: Chris Lamb <chris at chris-lamb.co.uk>

diff --git a/chapters/bugs.xml b/chapters/bugs.xml
deleted file mode 100644
index 41dfc65..0000000
--- a/chapters/bugs.xml
+++ /dev/null
@@ -1,101 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
-    "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
-  <!ENTITY % commondata SYSTEM "../ent/common.ent" > %commondata;
-]>
-<chapter id="bugs">
-<title>How to report a bug in Debian Live</title>
-
-<para><i>"No software is perfect... we need your help!"</i></para>
-
-<para>Debian Live is far from being perfect, but we want to make it as close as possible to perfect - with your help.</para>
-
-<para>As such, do not hesitate to report a bug:</para> it is better to fill a report twice or even to report a potential non-bug than no bug at all.</para>
-
-<para>However, here are some recommendations how to file good bug reports so that they are the most effective.</para>
-
-<para>For the impatient:</para>
-
-<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>
-
-<section>
-<title>Where does the bug appear?</title>
-
-<para>...at build time while bootstrapping?</para>
-
-<para>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.</para>
-
-<para>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.</para>
-
-<para>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.</para>
-
-<para>...at build time while installing packages?</para>
-
-<para>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.</para>
-
-<para>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.</para>
-
-<para>In all cases above, these are not a bug in live-helper, but rather in Debian
-again. Report it against the failing package(s).</para>
-
-<para>...at boot time?</para>
-
-<para>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.</para>
-
-<para>...at run time?</para>
-
-<para>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.</para>
-</section>
-
-<section>
-<title>Where to send the bug report?</title>
-
-<para>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.</para>
-
-<para>To make the most out of your bug report, we require at least the following
-information:</para>
-
-<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>
-
-<para>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.</para>
-
-</section>
-
-</chapter>
diff --git a/chapters/reporting-bugs.xml b/chapters/reporting-bugs.xml
index 1eabbe3..10b6924 100644
--- a/chapters/reporting-bugs.xml
+++ b/chapters/reporting-bugs.xml
@@ -6,7 +6,22 @@
 <chapter id="bugs">
 <title>Reporting bugs</title>
 
-<para>Debian Live is far from being perfect, but we want to make it as close as possible to perfect - with your help. Do not hesitate to report a bug: it is better to fill a report twice than never. However, here are some recommendations how to file good bug reports:</para>
+<para>Debian Live is far from being perfect, but we want to make it as close as possible to perfect - with your help. Do not hesitate to report a bug: it is better to fill a report twice than never. However, this chapter includes recommendations how to file good bug reports.</para>
+
+<para>For the impatient:</para>
+
+<itemizedlist>
+<listitem>
+ <para>
+  Always try to reproduce the bug with the <emphasis>most recent version of <filename>live-helper</filename> and <filename>live-initramfs</filename></emphasis> before submitting a bug report.
+ </para>
+</listitem>
+<listitem>
+ <para>
+  Try to give <emphasis>as specific information as possible</emphasis> about the bug. This includes (at least) the version of <filename>live-helper</filename> and <filename>live-initramfs</filename> used and the distribution of the live system you are building.
+ </para>
+</listitem>
+</itemizedlist>
 
 <section id="up-to-date">
 <title>Use up-to-date packages</title>
@@ -20,6 +35,26 @@
 <title>Collect information</title>
 
 <para>Please provide enough information with your report. At a minimum, it should contain the exact version of live-helper version where the bug is encountered, and steps to reproduce it. Please use common sense and include other relevant information if you think that it might help in solving the problem.</para>
+
+<para>To make the most out of your bug report, we require at least the following
+information:</para>
+
+<itemizedlist>
+ <listitem><para>Architecture of the host system</para></listitem>
+ <listitem><para>Version of <filename>live-helper</filename> on the host system</para></listitem>
+ <listitem><para>Version of <filename>live-initramfs</filename> on the live system</para></listitem>
+ <listitem><para>Version of <filename>debootstrap</filename> and/or <filename>cdebootstrap</filename> on the host system</para></listitem>
+ <listitem><para>Architecture of the live system</para></listitem>
+ <listitem><para>Distribution of the live system</para></listitem>
+ <listitem><para>Version of the kernel on the live system</para></listitem>
+</itemizedlist>
+
+<para>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.</para>
+
+
 </section>
 
 <section id="correct-package">
@@ -43,9 +78,23 @@
 
 <listitem><para><filename>live-helper</filename> installs additional packages from the Debian archive and 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 system.</para>
 
-<para>If this is the case, this is not a bug in Debian Live, but rather in Debian. Report it against the failing package.</para></listitem>
+<para>If this is the case, this is not a bug in Debian Live, but rather in Debian - please report it against the failing package. Running <filename>debootstrap</filename> seperately from the Live system build or running <filename>lh_bootstrap</filename> with <computeroutput>--debug</computeroutput> will give you more information.</para>
+
+<para>Also, if you are using a local mirror and/or any of sort of proxy and you are experiencing a problem, please always reproduce it first by bootstrapping from an official mirror.</para>
+
+</listitem>
+
 </varlistentry>
 
+<varlistentry>
+ <term>At boot-time</term>
+ <listitem>
+  <para>
+   If your image does not boot, please report it to the mailing list together with the information requested in <xref linkend="collect-information"/>. 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, please always run it on real hardware before reporting a bug. Providing a screenshot of the failure is also very helpful.
+  </para>
+ </listitem>
+</varlistentry> 
+
 <varlistentry><term>At run-time</term>
 
 <listitem><para>If a package was successfully installed, but fails while actually running the Live system, this is probably a bug in Debian Live. However, </para></listitem>

-- 
Debian Live manual

