Merge lp:~petermatulis/serverguide/review_reporting-bugs into lp:serverguide/trunk

[Peter Matulis]

Same as the one pushed to Utopic.

[Doug Smythies (dsmythies)]

Peter, it looks good thanks. I couldn't submit a test bug report against the "Ubuntu Server Guide" because it is not a package. I did submit one against "docbook" and it is pending, and I hope it will delete by itself after some time when I don't finish it.

review: Approve

=== modified file 'serverguide/C/reporting-bugs.xml'
--- serverguide/C/reporting-bugs.xml	2013-03-23 22:09:27 +0000
+++ serverguide/C/reporting-bugs.xml	2014-07-18 20:40:54 +0000
@@ -14,74 +14,57 @@
     <title>Reporting Bugs in Ubuntu Server Edition</title>
 
   <para>
-  While the Ubuntu Project attempts to release software with as few
-  bugs as possible, they do occur. You can help fix these bugs by
-  reporting ones that you find to the project.  The Ubuntu Project
-  uses <ulink url="https://launchpad.net/">Launchpad</ulink>
-  to track its bug reports. In order to file a bug
-  about Ubuntu Server on Launchpad, you will need to
-  <ulink url="https://help.launchpad.net/YourAccount/NewAccount">create
-  an account</ulink>.
+  The Ubuntu Project, and thus Ubuntu Server, uses <ulink url="https://launchpad.net/">Launchpad</ulink>
+  as its bugtracker. In order to file a bug, you will need a Launchpad account.  <ulink url="https://help.launchpad.net/YourAccount/NewAccount">Create
+  one here</ulink> if necessary.
   </para>
 
-  <sect2 id="reporting-bugs-ubuntu-bug" status="review">
-    <title>Reporting Bugs With ubuntu-bug</title>
-
-    <para>
-    The preferred way to report a bug is with the
-    <application>ubuntu-bug</application> command. The ubuntu-bug
-    tool gathers information about the system useful to developers in
-    diagnosing the reported problem that will then be included in the
-    bug report filed on Launchpad. Bug reports in Ubuntu need to be
-    filed against a specific software package, thus the name of the
-    package that the bug occurs in needs to be given to ubuntu-bug:
-    </para>
-
-<screen>
-<command>ubuntu-bug PACKAGENAME</command>
-</screen>
-
-    <para>
-    For example, to file a bug against the openssh-server package, you would do:
-    </para>
-
-<screen>
-<command>ubuntu-bug openssh-server</command>
-</screen>
-
-    <para>
-    You can specify either a binary package or the source package
-    for ubuntu-bug. Again using openssh-server as an example,
-    you could also generate the report against the source package
-    for openssh-server, openssh:
-    </para>
-
-<screen>
-<command>ubuntu-bug openssh</command>
+  <sect2 id="reporting-bugs-apport-cli" status="review">
+    <title>Reporting Bugs With apport-cli</title>
+
+    <para>
+	    The preferred way to report a bug is with the <application>apport-cli</application> command.  It must be invoked on the machine affected by the bug
+	    because it collects information from the system on which it is being run and publishes it to the bug report on Launchpad.  Getting that information to
+	    Launchpad can therefore be a challenge if the system is not running a desktop environment in order to use a browser (common with servers) or if it does
+	    not have Internet access.  The steps to take in these situations are described below. 
+    </para>
+
+	<note>
+	<para>
+	The commands <application>apport-cli</application> and <application>ubuntu-bug</application> should give the same results on a CLI server.
+	The latter is actually a symlink to <application>apport-bug</application> which is intelligent enough to know whether a desktop environment is in use and
+	will choose <application>apport-cli</application> if not.  Since server systems tend to be CLI-only apport-cli was chosen from the outset in this guide.
+	</para>
+	</note>
+
+    <para>
+    Bug reports in Ubuntu need to be filed against a specific software package, so the name of the
+    package (source package or program name/path) affected by the bug needs to be supplied to apport-cli:
+    </para>
+
+<screen>
+<command>apport-cli PACKAGENAME</command>
 </screen>
 
     <note>
     <para>
-    See <xref linkend="package-management"/>
-    for more information about packages in Ubuntu.
+    See <xref linkend="package-management"/> for more information about packages in Ubuntu.
     </para>
     </note>
 
     <para>
-    The ubuntu-bug command will gather information about the system in
-    question, possibly including information specific to the specified
-    package, and then ask you what you would like to do with collected
-    information:
+    Once apport-cli has finished gathering information you will be asked what to do with it.  For
+    instance, to report a bug in vim:
     </para>
 
 <screen>
-<command>ubuntu-bug postgresql</command>
+<command>apport-cli vim</command>
 
 *** Collecting problem information
 
 The collected information can be sent to the developers to improve the
 application. This might take a few minutes.
-..........
+...
 
 *** Send problem report to the developers?
 
@@ -89,117 +72,115 @@
 automatically opened web browser.
 
 What would you like to do? Your options are:
-  S: Send report (1.7 KiB)
+  S: Send report (2.8 KB)
   V: View report
   K: Keep report file for sending later or copying to somewhere else
+  I: Cancel and ignore future crashes of this program version
   C: Cancel
-Please choose (S/V/K/C):
+Please choose (S/V/K/I/C):
 </screen>
 
     <para>
-    The options available are:
+    The first three options are described below:
     </para>
 
     <para>
     <itemizedlist>
       <listitem>
-        <para><emphasis role="bold">Send Report</emphasis> Selecting
-        Send Report submits the collected information to Launchpad as
-        part of the process of filing a bug report. You will be
-        given the opportunity to describe the situation that led up to
-        the occurrence of the bug.
+        <para><emphasis role="bold">Send:</emphasis> 
+        submits the collected information to Launchpad as part of the process
+	of filing a new bug report. You will be given the opportunity to describe
+	the bug in your own words.
         </para>
 
 <screen>
+
 *** Uploading problem information
 
 The collected information is being sent to the bug tracking system.
 This might take a few minutes.
-91%
+94%
 
 *** To continue, you must visit the following URL:
 
-https://bugs.launchpad.net/ubuntu/+source/postgresql-8.4/+filebug/kc6eSnTLnLxF8u0t3e56EukFeqJ?
-
-You can launch a browser now, or copy this URL into a browser on another
-computer.
+  https://bugs.launchpad.net/ubuntu/+source/vim/+filebug/09b2495a-e2ab-11e3-879b-68b5996a96c8?
+
+You can launch a browser now, or copy this URL into a browser on another computer.
+
 
 Choices:
   1: Launch a browser now
   C: Cancel
-Please choose (1/C):
-</screen>
-
-        <para>
-        If you choose to start a browser, by default the text based web
-        browser <application>w3m</application> will be used to finish filing
-        the bug report. Alternately, you can copy the given URL to a
-        currently running web browser.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-        <emphasis role="bold">View Report</emphasis> Selecting View
-        Report causes the collected information to be displayed to
-        the terminal for review.
-        </para>
-
-<screen>
-Package: postgresql 8.4.2-2
-PackageArchitecture: all
-Tags: lucid
-ProblemType: Bug
-ProcEnviron:
-  LANG=en_US.UTF-8
-  SHELL=/bin/bash
-Uname: Linux 2.6.32-16-server x86_64
-Dependencies:
-  adduser 3.112ubuntu1
-  base-files 5.0.0ubuntu10
-  base-passwd 3.5.22
-  coreutils 7.4-2ubuntu2
-...
-</screen>
-
-        <para>
-        After viewing the report, you will be brought back to the same
-        menu asking what you would like to do with the report.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-        <emphasis role="bold">Keep Report File</emphasis> Selecting Keep
-        Report File causes the gathered information to be written to
-        a file. This file can then be used to later file a bug report
-        or transferred to a different Ubuntu system for reporting.
-        To submit the report file, simply give it as an argument to
-        the ubuntu-bug command:
+Please choose (1/C):  <userinput>1</userinput>
+</screen>
+
+        <para>
+        The browser that will be used when choosing '1' will be the one known on the system as
+	<application>www-browser</application> via the
+	<ulink url="http://manpages.ubuntu.com/manpages/en/man8/update-alternatives.8.html">
+	Debian alternatives system</ulink>.  Examples of text-based browsers to install include <application>links</application>,
+	<application>elinks</application>, <application>lynx</application>, and <application>w3m</application>.
+	You can also manually point an existing browser at the given URL.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+        <emphasis role="bold">View:</emphasis>
+	displays the collected information on the screen for review.  This can
+	be a lot of information.  Press 'Enter' to scroll by screenful.  Press 'q'
+	to quit and return to the choice menu.
+        </para>
+      </listitem>
+
+      <listitem>
+        <para>
+        <emphasis role="bold">Keep:</emphasis>
+        writes the collected information to disk. The resulting file can be later used to
+	file the bug report, typically after transferring it to another Ubuntu system.
         </para>
 
 <screen>
 What would you like to do? Your options are:
-  S: Send report (1.7 KiB)
+  S: Send report (2.8 KB)
   V: View report
   K: Keep report file for sending later or copying to somewhere else
+  I: Cancel and ignore future crashes of this program version
   C: Cancel
-Please choose (S/V/K/C): <userinput>k</userinput>
-Problem report file: /tmp/apport.postgresql.v4MQas.apport
-
-<command>ubuntu-bug /tmp/apport.postgresql.v4MQas.apport</command>
-
-*** Send problem report to the developers?
-...
-</screen>
-      </listitem>
-
-      <listitem>
-        <para>
-        <emphasis role="bold">Cancel</emphasis> Selecting
-        Cancel causes the collected information to be discarded.
-        </para>
-      </listitem>
+Please choose (S/V/K/I/C): <userinput>k</userinput>
+Problem report file: /tmp/apport.vim.1pg92p02.apport
+</screen>
+
+	<para>
+	To report the bug, get the file onto an internet-enabled Ubuntu system and apply apport-cli
+	to it. This will cause the menu to appear immediately (the information is already collected).
+	You should then press 's' to send:
+	</para>
+
+<screen>
+<command>apport-cli apport.vim.1pg92p02.apport</command>
+</screen>
+
+<para>
+To directly save a report to disk (without menus) you can do:
+
+<screen>
+<command>apport-cli vim --save apport.vim.test.apport</command>
+</screen>
+
+Report names should end in <emphasis>.apport</emphasis> .
+</para>
+
+	<note>
+	<para>
+		If this internet-enabled system is non-Ubuntu/Debian, apport-cli is not available so the
+		bug will need to be created manually.  An apport report is also not to be included as an
+		attachment to a bug either so it is completely useless in this scenario.
+	</para>
+	</note>
+
+      </listitem>
+
     </itemizedlist>
     </para>
   </sect2>
@@ -207,89 +188,58 @@
   <sect2 id="apport-crash-catching" status="review">
     <title>Reporting Application Crashes</title>
 
-    <para>
-    The software package that provides the ubuntu-bug utility, 
-    <application>apport</application>, can be configured to trigger
-    when applications crash. This is disabled by default, as capturing
-    a crash can be resource intensive depending on how much memory
-    the application that crashed was using as apport captures and
-    processes the core dump.
-    </para>
-
-    <para>
-    Configuring apport to capture information about
-    crashing applications requires a couple of steps. First,
-    <application>gdb</application> needs to be installed; it is not
-    installed by default in Ubuntu Server Edition.
-    </para>
-
-<screen>
-<command>sudo apt-get install gdb</command>
-</screen>
-
-    <para>
-    See <xref linkend="package-management"/>
-    for more information about managing packages in Ubuntu.
-    </para>
-
-    <para>
-    Once you have ensured that gdb is installed, open the file
-    <filename>/etc/default/apport</filename> in your text editor,
-    and change the <emphasis>enabled</emphasis> setting to be
-    <emphasis role="bold">1</emphasis> like so:
-    </para>
-
-<programlisting>
-# set this to 0 to disable apport, or to 1 to enable it
-# you can temporarily override this with
-# sudo service apport start force_start=1
-enabled=<userinput>1</userinput>
-
-# set maximum core dump file size (default: 209715200 bytes == 200 MB)
-maxsize=209715200
-</programlisting>
-
-    <para>
-    Once you have completed editing
-    <filename>/etc/default/apport</filename>,
-    start the apport service:
-    </para>
-
-<screen>
-<command>sudo start apport</command>
-</screen>
-
-    <para>
-    After an application crashes, use the
-    <application>apport-cli</application> command to search for the
-    existing saved crash report information:
-    </para>
+	<para>
+    	The software package that provides the apport-cli utility, <application>apport</application>,
+	can be configured to automatically capture the state of a crashed application.  This
+	is enabled by default (in <filename>/etc/default/apport</filename>).
+	</para>
+
+	<para>
+	After an application crashes, if enabled, apport will store a crash report under <filename>/var/crash</filename>:
+	</para>
+
+<screen>
+-rw-r----- 1 peter    whoopsie 150K Jul 24 16:17 _usr_lib_x86_64-linux-gnu_libmenu-cache2_libexec_menu-cached.1000.crash
+</screen>
+
+	<para>
+	Use the <application>apport-cli</application> command without arguments to process any pending crash reports.  It
+	will offer to report them one by one.
+	</para>
 
 <screen>
 <command>apport-cli</command>
 
-*** dash closed unexpectedly on 2010-03-11 at 21:40:59.
+*** Send problem report to the developers?
 
-If you were not doing anything confidential (entering passwords or other
-private information), you can help to improve the application by
-reporting
-the problem.
+After the problem report has been sent, please fill out the form in the
+automatically opened web browser.
 
 What would you like to do? Your options are:
-  R: Report Problem...
+  S: Send report (153.0 KB)
+  V: View report
+  K: Keep report file for sending later or copying to somewhere else
   I: Cancel and ignore future crashes of this program version
   C: Cancel
-Please choose (R/I/C):
-</screen>
-
-    <para>
-    Selecting <emphasis>Report Problem</emphasis> will walk you through
-    similar steps as when using ubuntu-bug. One important difference
-    is that a crash report will be marked as private when filed on
-    Launchpad, meaning that it will be visible to only a limited set
-    of bug triagers. These triagers will review the gathered data for private
-    information before making the bug report publicly visible.
-    </para>
+Please choose (S/V/K/I/C): <userinput>s</userinput>
+</screen>
+
+	<para>
+	If you send the report, as was done above, the prompt will be returned immediately and the
+	<filename>/var/crash</filename> directory will then contain 2 extra files:
+	</para>
+
+<screen>
+-rw-r----- 1 peter    whoopsie 150K Jul 24 16:17 _usr_lib_x86_64-linux-gnu_libmenu-cache2_libexec_menu-cached.1000.crash
+-rw-rw-r-- 1 peter    whoopsie    0 Jul 24 16:37 _usr_lib_x86_64-linux-gnu_libmenu-cache2_libexec_menu-cached.1000.upload
+-rw------- 1 whoopsie whoopsie    0 Jul 24 16:37 _usr_lib_x86_64-linux-gnu_libmenu-cache2_libexec_menu-cached.1000.uploaded
+</screen>
+
+	<para>
+	Sending in a crash report like this will not immediately result in the creation of a new public bug.
+	The report will be made private on Launchpad, meaning that it will be visible to only a limited set
+	of bug triagers. These triagers will then scan the report for possible private data before creating a public bug.
+	</para>
 
     <!-- Include a bit here on using apport-retrace for generating a
          full stack trace locally, for situations when the application
@@ -301,18 +251,20 @@
   <sect2 id="reporting-bugs-resources" status="review">
     <title>Resources</title>
     <itemizedlist>
+
       <listitem>
         <para>
-	See the <ulink url="https://help.ubuntu.com/community/ReportingBugs">Reporting
-	Bugs</ulink> Ubuntu wiki page.
+	See the <ulink url="https://help.ubuntu.com/community/ReportingBugs">Reporting Bugs</ulink> Ubuntu wiki page.
 	</para>
       </listitem>
+
       <listitem>
         <para>
-	    Also, the <ulink url="https://wiki.ubuntu.com/Apport">Apport</ulink> page has some useful information.  Though some
+	Also, the <ulink url="https://wiki.ubuntu.com/Apport">Apport</ulink> page has some useful information.  Though some
         of it pertains to using a GUI.
     	</para>
       </listitem>
+
     </itemizedlist>
   </sect2>
   </sect1>