summaryrefslogtreecommitdiff
path: root/templates/common/doc/bug-reporting.txt
diff options
context:
space:
mode:
Diffstat (limited to 'templates/common/doc/bug-reporting.txt')
-rw-r--r--templates/common/doc/bug-reporting.txt304
1 files changed, 304 insertions, 0 deletions
diff --git a/templates/common/doc/bug-reporting.txt b/templates/common/doc/bug-reporting.txt
new file mode 100644
index 000000000..ca14c2ae9
--- /dev/null
+++ b/templates/common/doc/bug-reporting.txt
@@ -0,0 +1,304 @@
+How to report a bug in Debian
+
+Important things to note before sending
+
+ Please don't report multiple unrelated bugs - especially ones in
+ different packages - in a single bug report. It makes our lives much
+ easier if you send separate reports.
+
+ You should check if your bug report has already been filed by someone
+ else before submitting it. Lists of currently outstanding bugs are
+ available on the World Wide Web and elsewhere - see other documents
+ for details. You can submit your comments to an existing bug report
+ #<number> by sending e-mail to <number>@bugs.debian.org
+
+ If you can't seem to determine which package contains the problem,
+ please send e-mail to the Debian user mailing list asking for advice.
+ If your problem doesn't relate just to one package but some general
+ Debian service, there are several pseudo-packages or even mailing
+ lists that you can use to relay your message to us instead.
+
+ If you'd like to send a copy of your bug report to additional
+ recipients (such as mailing lists), you shouldn't use the usual e-mail
+ headers, but a different method, described below.
+
+Sending the bug report using an automatic bug report tool
+
+ The reportbug program can ease filing bugs by guiding you through the
+ bug reporting process step by step. The querybts tool, available from
+ the same package as reportbug, provides a convenient text-based
+ interface to the bug tracking system.
+
+ Emacs users can also use the debian-bug command provided by the
+ debian-el package. When called with M-x debian-bug, it will ask for
+ all necessary information in a similar way to reportbug.
+
+Sending the bug report via e-mail
+
+ Send email to submit@bugs.debian.org, as described below.
+
+ Of course, like any email, you should include a clear, descriptive
+ Subject line in your main mail header. The subject you give will be
+ used as the initial bug title in the tracking system, so please try to
+ make it informative!
+
+ You need to put a pseudo-header at the start of the body of the
+ message. That means that the first line of the message body should
+ say:
+Package: <something>
+
+ Replace <something> with the name of the package which has the bug.
+
+ The second line of the message should say:
+Version: <something>
+
+ Replace <something> with the version of the package. Please don't
+ include any text here other than the version itself, as the bug
+ tracking system relies on this field to work out which releases are
+ affected by the bug.
+
+ You need to supply a correct Package line in the pseudo-header in
+ order for the bug tracking system to deliver the message to the
+ package's maintainer. See this example for information on how to find
+ this information.
+
+ The pseudo-header fields should start at the very start of their
+ lines.
+
+ Please include in your report:
+ * The exact and complete text of any error messages printed or
+ logged. This is very important!
+ * Exactly what you typed or did to demonstrate the problem.
+ * A description of the incorrect behaviour: exactly what behaviour
+ you were expecting, and what you observed. A transcript of an
+ example session is a good way of showing this.
+ * A suggested fix, or even a patch, if you have one.
+ * Details of the configuration of the program with the problem.
+ Include the complete text of its configuration files.
+ * The versions of any packages on which the buggy package depends.
+ * What kernel version you're using (type uname -a), your shared C
+ library (type ls -l /lib/libc.so.6 or dpkg -s libc6 | grep
+ ^Version), and any other details about your Debian system, if it
+ seems appropriate. For example, if you had a problem with a Perl
+ script, you would want to provide the version of the `perl' binary
+ (type perl -v or dpkg -s perl | grep ^Version:).
+ * Appropriate details of the hardware in your system. If you're
+ reporting a problem with a device driver please list all the
+ hardware in your system, as problems are often caused by IRQ and
+ I/O address conflicts.
+
+ Include any detail that seems relevant - you are in very little danger
+ of making your report too long by including too much information. If
+ they are small please include in your report any files you were using
+ to reproduce the problem (uuencoding them if they may contain odd
+ characters etc.).
+
+ For more advice on how to help the developers solve your problem,
+ please read How to Report Bugs Effectively.
+
+Example
+
+ A bug report, with mail header, looks something like this:
+ To: submit@bugs.debian.org
+ From: diligent@testing.linux.org
+ Subject: Hello says `goodbye'
+
+ Package: hello
+ Version: 1.3-16
+
+ When I invoke `hello' without arguments from an ordinary shell
+ prompt it prints `goodbye', rather than the expected `hello, world'.
+ Here is a transcript:
+
+ $ hello
+ goodbye
+ $ /usr/bin/hello
+ goodbye
+ $
+
+ I suggest that the output string, in hello.c, be corrected.
+
+ I am using Debian GNU/Linux 2.2, kernel 2.2.17-pre-patch-13
+ and libc6 2.1.3-10.
+
+Sending copies of bug reports to other addresses
+
+ Sometimes it is necessary to send a copy of a bug report to somewhere
+ else besides debian-bugs-dist and the package maintainer, which is
+ where they are normally sent.
+
+ You could do this by CC'ing your bug report to the other address(es),
+ but then the other copies would not have the bug report number put in
+ the Reply-To field and the Subject line. When the recipients reply
+ they will probably preserve the submit@bugs.debian.org entry in the
+ header and have their message filed as a new bug report. This leads to
+ many duplicated reports.
+
+ The right way to do this is to use the X-Debbugs-CC header. Add a line
+ like this to your message's mail header:
+ X-Debbugs-CC: other-list@cosmic.edu
+
+ This will cause the bug tracking system to send a copy of your report
+ to the address(es) in the X-Debbugs-CC line as well as to
+ debian-bugs-dist.
+
+ Avoid sending such copies to the addresses of other bug reports, as
+ they will be caught by the checks that prevent mail loops. There is
+ relatively little point in using X-Debbugs-CC for this anyway, as the
+ bug number added by that mechanism will just be replaced by a new one;
+ use an ordinary CC header instead.
+
+ This feature can often be combined usefully with mailing quiet - see
+ below.
+
+Severity levels
+
+ If a report is of a particularly serious bug, or is merely a feature
+ request that, you can set the severity level of the bug as you report
+ it. This is not required, however, and the developers will assign an
+ appropriate severity level to your report if you do not.
+
+ To assign a severity level, put a line like this one in the
+ pseudo-header:
+Severity: <severity>
+
+ Replace <severity> with one of the available severity levels, as
+ described in the developers' documentation.
+
+Assigning tags
+
+ You can set tags on a bug as you are reporting it. For example, if you
+ are including a patch with your bug report, you may wish to set the
+ patch tag. This is not required, however, and the developers will set
+ tags on your report as and when it is appropriate.
+
+ To set tags, put a line like this one in the pseudo-header:
+Tags: <tags>
+
+ Replace <tags> with one or more of the available tags, as described in
+ the developers' documentation. Separate multiple tags with commas,
+ spaces, or both.
+
+Other pseudo headers (primarily of interest to package maintainers)
+
+Forwarded: foo@example.com
+
+ will mark the newly submitted bug as forwarded to foo@example.com. See
+ Recording that you have passed on a bug report in the developers'
+ documentation for details.
+Owner: foo@example.com
+
+ will indicate that foo@example.com is now responsible for fixing this
+ bug. See Changing bug ownership in the developers' documentation for
+ details.
+Source: foopackage
+
+ the equivalent of Package: for bugs present in the source package of
+ foopackage; for most bugs in most packages you don't want to use this
+ option.
+
+ Finally, if your MUA doesn't allow you to edit the headers, you can
+ set the various X-Debbugs- headers in the pseudo-headers.
+
+Different submission addresses (minor or mass bug reports)
+
+ If a bug report is minor, for example, a documentation typo or a
+ trivial build problem, please adjust the severity appropriately and
+ send it to maintonly@bugs instead of submit@bugs. maintonly will
+ forward the report to the package maintainer only, it won't forward it
+ to the BTS mailing lists.
+
+ If you're submitting many reports at once, you should definitely use
+ maintonly@bugs so that you don't cause too much redundant traffic on
+ the BTS mailing lists. Before submitting many similar bugs you may
+ also want to post a summary on debian-bugs-dist.
+
+ If wish to report a bug to the bug tracking system that's already been
+ sent to the maintainer, you can use quiet@bugs. Bugs sent to
+ quiet@bugs will not be forwarded anywhere, only filed.
+
+ When you use different submission addresses, the bug tracking system
+ will set the Reply-To of any forwarded message so that the replies
+ will by default be processed in the same way as the original report.
+ That means that, for example, replies to maintonly will go to
+ nnn-maintonly@bugs instead of nnn@bugs, unless of course one overrides
+ this manually.
+
+Acknowledgements
+
+ Normally, the bug tracking system will return an acknowledgement to
+ you by e-mail when you report a new bug or submit additional
+ information to an existing bug. If you want to suppress this
+ acknowledgement, include an X-Debbugs-No-Ack header in your e-mail
+ (the contents of this header do not matter; however, it must be in the
+ mail header and not in the pseudo-header with the Package field). If
+ you report a new bug with this header, you will need to check the web
+ interface yourself to find the bug number.
+
+ Note that this header will not suppress acknowledgements from the
+ control@bugs mailserver, since those acknowledgements may contain
+ error messages which should be read and acted upon.
+
+Bug reports against unknown packages
+
+ If the bug tracking system doesn't know who the maintainer of the
+ relevant package is it'll forward the report to debian-bugs-dist even
+ if maintonly was used.
+
+ When sending to maintonly@bugs or nnn-maintonly@bugs you should make
+ sure that the bug report is assigned to the right package, by putting
+ a correct Package at the top of an original submission of a report, or
+ by using the control@bugs service to (re)assign the report
+ appropriately first if it isn't correct already.
+
+Using dpkg to find the package and version for the report
+
+ If you are reporting a bug in a command, you can find out which
+ package installed it by using dpkg --search. You can find out which
+ version of a package you have installed by using dpkg --list or dpkg
+ --status.
+
+ For example:
+$ which apt-get
+/usr/bin/apt-get
+$ type apt-get
+apt-get is /usr/bin/apt-get
+$ dpkg --search /usr/bin/apt-get
+apt: /usr/bin/apt-get
+$ dpkg --list apt
+Desired=Unknown/Install/Remove/Purge/Hold
+| Status=Not/Installed/Config-files/Unpacked/Failed-config/Half-installed
+|/ Err?=(none)/Hold/Reinst-required/X=both-problems (Status,Err: uppercase=bad)
+||/ Name Version Description
++++-==============-==============-============================================
+ii apt 0.3.19 Advanced front-end for dpkg
+$ dpkg --status apt
+Package: apt
+Status: install ok installed
+Priority: standard
+Section: base
+Installed-Size: 1391
+Maintainer: APT Development Team <deity@lists.debian.org>
+Version: 0.3.19
+Replaces: deity, libapt-pkg-doc (<< 0.3.7), libapt-pkg-dev (<< 0.3.7)
+Provides: libapt-pkg2.7
+Depends: libapt-pkg2.7, libc6 (>= 2.1.2), libstdc++2.10
+Suggests: dpkg-dev
+Conflicts: deity
+Description: Advanced front-end for dpkg
+ This is Debian's next generation front-end for the dpkg package manager.
+ It provides the apt-get utility and APT dselect method that provides a
+ simpler, safer way to install and upgrade packages.
+ .
+ APT features complete installation ordering, multiple source capability
+ and several other unique features, see the Users Guide in
+ /usr/doc/apt/guide.text.gz
+ _________________________________________________________________
+
+ Debian BTS administrators <owner@bugs.debian.org>
+
+ Debian bug tracking system
+ Copyright © 1999 Darren O. Benham, 1997, 2003 nCipher Corporation Ltd,
+ 1994-1997 Ian Jackson.
+ _________________________________________________________________
+