Ubuntu Documentation

Merge lp:~sbeattie/ubuntu-docs/serverguide-apport into lp:ubuntu-docs/lucid

  1. serverguide-apport
  2. Merge into lucid
Proposed by Steve Beattie
Status: Rejected
Rejected by: Connor Imes
Proposed branch: lp:~sbeattie/ubuntu-docs/serverguide-apport
Merge into: lp:ubuntu-docs/lucid
Diff against target: 327 lines (+314/-0)
2 files modified
serverguide/C/reporting-bugs.xml (+313/-0)
serverguide/C/serverguide.xml (+1/-0)
To merge this branch: bzr merge lp:~sbeattie/ubuntu-docs/serverguide-apport
Reviewer Review Type Date Requested Status
Steve Beattie (community) Needs Resubmitting
Connor Imes (community) Needs Fixing
Review via email: mp+21893@code.launchpad.net

Description of the change

Add an appendix section that describes how to report bugs ubuntu-server. (LP: #544560)

To post a comment you must log in.
Revision history for this message
Connor Imes (ckimes) wrote :

Steve, thanks for your work. Unfortunately this does not validate in the serverguide after merging locally:
   scripts/validate.sh serverguide/C/serverguide.xml
We have not used appendixes elsewhere, so I'm not entirely sure on how to use it correctly (from what I can tell it should work, but isn't). If you can't get it to validate, using a chapter instead of an appendix will be OK. Also, a <title> tag does not need an id attribute. Finally, <note> tags need to have <para> tags embedded in them.
Please fix ASAP and I will merge before String Freeze. Cheers.

review: Needs Fixing
lp:~sbeattie/ubuntu-docs/serverguide-apport updated
462. By Steve Beattie

- serverguide/C/reporting-bugs.xml: fixups based on feedback from Connor Imes
  - converted sect2s to sect1s; this makes the document pass the
    validation script. I still feel it's awkward this way, but the other
    way is not valid docbook xml. They could be converted to
    simplesects, though they'd need the attributes removed and it
    wouldn't match the other chapters.
  - wrapped note text in para tags
  - removed id attribute from title tag
  - converted Resources section to References, to match the rest of the
    server guide chapters.

463. By Steve Beattie

- serverguide/C/reporting-bugs.xml: style fixup, With -> with in title section

Revision history for this message
Steve Beattie (sbeattie) wrote :

Connor, thanks for the feedback. I was unaware of the validate.sh script, can it be mentioned at https://wiki.ubuntu.com/DocumentationTeam/StyleGuide/DocbookConventions or another location? I did try to read the style guide while writing this section.

I have fixed the reporting-bugs.xml document so that the server guide passes validation; the issue was that I used sect2 sections without any sect1 sections, which is obviously silly on my part. However, I think I did that because I didn't like having the sections be first level sections and broken out in the ToC and the first page of the appendix. I could convert them to simplesects, but that wouldn't match the rest of the documentation style.

I have also fixed the para inside note issue, removed the id from the title, changed the Resources section to References to be consistent with the rest of the book, and fixed a stylistic tidbit (With -> with) in one of the section titles.

Thanks again!

review: Needs Resubmitting
Revision history for this message
Matthew East (mdke) wrote :

On Tue, Mar 23, 2010 at 5:12 AM, Steve Beattie <email address hidden> wrote:
> Connor, thanks for the feedback. I was unaware of the validate.sh script, can it be mentioned at https://wiki.ubuntu.com/DocumentationTeam/StyleGuide/DocbookConventions or another location?

Hi Steve,

It's mentioned at
https://wiki.ubuntu.com/DocumentationTeam/SystemDocumentation/Checking
which I think is the appropriate place. I don't think it's really a
point for the style guide. However if you think there is a specific
reason why you weren't aware of the "Checking" page - let us know and
we can try and make it more prominent.

--
Matthew East
http://www.mdke.org
gnupg pub 1024D/0E6B06FF

Revision history for this message
Connor Imes (ckimes) wrote :

I set that status to rejected, given that the merge was done manually. Thanks for your contributions, Steve - good work!

Unmerged revisions

463. By Steve Beattie

- serverguide/C/reporting-bugs.xml: style fixup, With -> with in title section

462. By Steve Beattie

- serverguide/C/reporting-bugs.xml: fixups based on feedback from Connor Imes
  - converted sect2s to sect1s; this makes the document pass the
    validation script. I still feel it's awkward this way, but the other
    way is not valid docbook xml. They could be converted to
    simplesects, though they'd need the attributes removed and it
    wouldn't match the other chapters.
  - wrapped note text in para tags
  - removed id attribute from title tag
  - converted Resources section to References, to match the rest of the
    server guide chapters.

461. By Steve Beattie

merge

460. By Steve Beattie

More mergery.

459. By Steve Beattie

reporting-bugs.xml: a couple of wordsmithing cleanups (thanks to Carlos
de-Avillez for feedback).

Preview Diff

[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk
1=== added file 'serverguide/C/reporting-bugs.xml'
2--- serverguide/C/reporting-bugs.xml 1970-01-01 00:00:00 +0000
3+++ serverguide/C/reporting-bugs.xml 2010-03-23 05:10:39 +0000
4@@ -0,0 +1,313 @@
5+<?xml version="1.0" encoding="UTF-8"?>
6+<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
7+ "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
8+<!ENTITY % globalent SYSTEM "../../libs/global.ent">
9+%globalent;
10+<!ENTITY % gnome-menus-C SYSTEM "../../libs/gnome-menus-C.ent">
11+%gnome-menus-C;
12+<!ENTITY % xinclude SYSTEM "../../libs/xinclude.mod">
13+%xinclude;
14+<!ENTITY language "&EnglishAmerican;">
15+]>
16+
17+<appendix id="reporting-bugs" status="review">
18+ <title>Reporting Bugs in Ubuntu Server Edition</title>
19+
20+ <para>
21+ While the Ubuntu Project attempts to release software with as few
22+ bugs as possible, they do occur. You can help fix these bugs by
23+ reporting ones that you find to the project. The Ubuntu Project
24+ uses <ulink url="https://launchpad.net/">Launchpad</ulink>
25+ to track its bug reports. In order to file a bug
26+ about Ubuntu Server on Launchpad, you will need to
27+ <ulink url="https://help.launchpad.net/YourAccount/NewAccount">create
28+ an account</ulink>.
29+ </para>
30+
31+ <sect1 id="reporting-bugs-ubuntu-bug" status="review">
32+ <title>Reporting Bugs with ubuntu-bug</title>
33+
34+ <para>
35+ The preferred way to report a bug is with the
36+ <application>ubuntu-bug</application> command. The ubuntu-bug
37+ tool gathers information about the system useful to developers in
38+ diagnosing the reported problem that will then be included in the
39+ bug report filed on Launchpad. Bug reports in Ubuntu need to be
40+ filed against a specific software package, thus the name of the
41+ package that the bug occurs in needs to be given to ubuntu-bug:
42+ </para>
43+
44+<screen>
45+<command>ubuntu-bug PACKAGENAME</command>
46+</screen>
47+
48+ <para>
49+ For example, to file a bug against the openssh-server package, you would do:
50+ </para>
51+
52+<screen>
53+<command>ubuntu-bug openssh-server</command>
54+</screen>
55+
56+ <para>
57+ You can specify either a binary package or the related source
58+ package for ubuntu-bug. Again using openssh-server as an example,
59+ you could also generate the report against the source package
60+ for openssh-server, openssh:
61+ </para>
62+
63+<screen>
64+<command>ubuntu-bug openssh</command>
65+</screen>
66+
67+ <note>
68+ <para>
69+ See <xref linkend="package-management"/>
70+ for more information about packages in Ubuntu.
71+ </para>
72+ </note>
73+
74+ <para>
75+ The ubuntu-bug command will gather information about the system
76+ in question, possibly including information specific to the
77+ package, and then ask you what you would like to do with collected
78+ information:
79+ </para>
80+
81+<screen>
82+<command>ubuntu-bug postgresql</command>
83+
84+*** Collecting problem information
85+
86+The collected information can be sent to the developers to improve the
87+application. This might take a few minutes.
88+..........
89+
90+*** Send problem report to the developers?
91+
92+After the problem report has been sent, please fill out the form in the
93+automatically opened web browser.
94+
95+What would you like to do? Your options are:
96+ S: Send report (1.7 KiB)
97+ V: View report
98+ K: Keep report file for sending later or copying to somewhere else
99+ C: Cancel
100+Please choose (S/V/K/C):
101+</screen>
102+
103+ <para>
104+ The options available are:
105+ </para>
106+
107+ <para>
108+ <itemizedlist>
109+ <listitem>
110+ <para><emphasis role="bold">Send Report</emphasis> Selecting
111+ Send Report submits the collected information to Launchpad as
112+ part of the the process of filing a bug report. You will be
113+ given the opportunity to describe the situation that led up to
114+ the occurrance of the bug.
115+ </para>
116+
117+<screen>
118+*** Uploading problem information
119+
120+The collected information is being sent to the bug tracking system.
121+This might take a few minutes.
122+91%
123+
124+*** To continue, you must visit the following URL:
125+
126+ https://bugs.launchpad.net/ubuntu/+source/postgresql-8.4/+filebug/kc6eSnTLnLxF8u0t3e56EukFeqJ?
127+
128+You can launch a browser now, or copy this URL into a browser on another
129+computer.
130+
131+Choices:
132+ 1: Launch a browser now
133+ C: Cancel
134+Please choose (1/C):
135+</screen>
136+
137+ <para>
138+ If you choose to start a browser, by default the text based web
139+ browser <application>w3m</application> will be used to finish filing
140+ the bug report. Alternately, you can copy the given URL to a
141+ currently running web browser.
142+ </para>
143+ </listitem>
144+
145+ <listitem>
146+ <para>
147+ <emphasis role="bold">View Report</emphasis> Selecting View
148+ Report causes the collected information to be displayed to
149+ the terminal for review.
150+ </para>
151+
152+<screen>
153+Package: postgresql 8.4.2-2
154+PackageArchitecture: all
155+Tags: lucid
156+ProblemType: Bug
157+ProcEnviron:
158+ LANG=en_US.UTF-8
159+ SHELL=/bin/bash
160+Uname: Linux 2.6.32-16-server x86_64
161+Dependencies:
162+ adduser 3.112ubuntu1
163+ base-files 5.0.0ubuntu10
164+ base-passwd 3.5.22
165+ coreutils 7.4-2ubuntu2
166+...
167+</screen>
168+
169+ <para>
170+ After viewing the report, you will be brought back to the same
171+ menu asking what you would like to do with the report.
172+ </para>
173+ </listitem>
174+
175+ <listitem>
176+ <para>
177+ <emphasis role="bold">Keep Report File</emphasis> Selecting Keep
178+ Report File causes the gathered information to be written to
179+ a file. This file can then be used to later file a bug report
180+ or transferred to a different Ubuntu system for reporting.
181+ To submit the report file, simply give it as an argument to
182+ the ubuntu-bug command:
183+ </para>
184+
185+<screen>
186+What would you like to do? Your options are:
187+ S: Send report (1.7 KiB)
188+ V: View report
189+ K: Keep report file for sending later or copying to somewhere else
190+ C: Cancel
191+Please choose (S/V/K/C): <userinput>k</userinput>
192+Problem report file: /tmp/apport.postgresql.v4MQas.apport
193+
194+<command>ubuntu-bug /tmp/apport.postgresql.v4MQas.apport</command>
195+
196+*** Send problem report to the developers?
197+...
198+</screen>
199+ </listitem>
200+
201+ <listitem>
202+ <para>
203+ <emphasis role="bold">Cancel</emphasis> Selecting
204+ Cancel causes the collected information to be discarded.
205+ </para>
206+ </listitem>
207+ </itemizedlist>
208+ </para>
209+ </sect1>
210+
211+ <sect1 id="apport-crash-catching" status="review">
212+ <title>Reporting Application Crashes</title>
213+
214+ <para>
215+ The software package that provides the ubuntu-bug utility,
216+ <application>apport</application>, can be configured to trigger
217+ when applications crash. This is disabled by default, as capturing
218+ a crash can be resource intensive depending on how much memory
219+ the application that crashed was using as apport captures and
220+ processes the core dump.
221+ </para>
222+
223+ <para>
224+ Configuring apport to capture information about
225+ crashing applications requires a couple of steps. First,
226+ <application>gdb</application> needs to be installed; it is not
227+ installed by default in Ubuntu Server Edition.
228+ </para>
229+
230+<screen>
231+<command>sudo apt-get install gdb</command>
232+</screen>
233+
234+ <para>
235+ See <xref linkend="package-management"/>
236+ for more information about managing packages in Ubuntu.
237+ </para>
238+
239+ <para>
240+ Once you have ensured that gdb is installed, open the file
241+ <filename>/etc/default/apport</filename> in your text editor,
242+ and change the <emphasis>enabled</emphasis> setting to be
243+ <emphasis role="bold">1</emphasis> like so:
244+ </para>
245+
246+<programlisting>
247+# set this to 0 to disable apport, or to 1 to enable it
248+# you can temporarily override this with
249+# sudo service apport start force_start=1
250+enabled=<userinput>1</userinput>
251+
252+# set maximum core dump file size (default: 209715200 bytes == 200 MB)
253+maxsize=209715200
254+</programlisting>
255+
256+ <para>
257+ Once you have completed editing
258+ <filename>/etc/default/apport</filename>,
259+ start the apport service:
260+ </para>
261+
262+<screen>
263+<command>sudo start apport</command>
264+</screen>
265+
266+ <para>
267+ After an application crashes, use the
268+ <application>apport-cli</application> command to search for the
269+ existing saved crash report information:
270+ </para>
271+
272+<screen>
273+<command>apport-cli</command>
274+
275+*** dash closed unexpectedly on 2010-03-11 at 21:40:59.
276+
277+If you were not doing anything confidential (entering passwords or other
278+private information), you can help to improve the application by
279+reporting
280+the problem.
281+
282+What would you like to do? Your options are:
283+ R: Report Problem...
284+ I: Cancel and ignore future crashes of this program version
285+ C: Cancel
286+Please choose (R/I/C):
287+</screen>
288+
289+ <para>
290+ Selecting <emphasis>Report Problem</emphasis> will walk you through
291+ similar steps as when using ubuntu-bug. One important difference
292+ is that a crash report will be marked as private when filed on
293+ Launchpad, meaning that it will be visible to only a limited set
294+ of bug triagers. These triagers will review the gathered data for private
295+ information before making the bug report publicly visible.
296+ </para>
297+
298+ <!-- Include a bit here on using apport-retrace for generating a
299+ full stack trace locally, for situations when the application
300+ does contain confidential information that should not be
301+ submitted to launchpad? -->
302+
303+ </sect1>
304+
305+ <sect1 id="reporting-bugs-resources" status="review">
306+ <title>References</title>
307+ <itemizedlist>
308+ <listitem>
309+ <para>
310+ See the <ulink url="https://help.ubuntu.com/community/ReportingBugs">Reporting
311+ Bugs</ulink> Ubuntu wiki page.
312+ </para>
313+ </listitem>
314+ </itemizedlist>
315+ </sect1>
316+
317+</appendix>
318
319=== modified file 'serverguide/C/serverguide.xml'
320--- serverguide/C/serverguide.xml 2009-08-04 02:53:02 +0000
321+++ serverguide/C/serverguide.xml 2010-03-23 05:10:39 +0000
322@@ -45,4 +45,5 @@
323 <xi:include href="clustering.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
324 <xi:include href="vpn.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
325 <xi:include href="other-apps.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
326+ <xi:include href="reporting-bugs.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
327 </book>

Subscribers

People subscribed via source and target branches