debian_reportbug/doc/README.Users

===============================
reportbug Information for Users
===============================

How to use GMail SMTP server
============================

You have to set these variables in ~/.reportbugrc file:

smtphost smtp.googlemail.com:587
smtpuser "<your address>@gmail.com"
smtptls

Thanks to: Raphael Geissert <atomo64@gmail.com>

How to Usertags a Bug at Report Time
====================================

If you're filing a bug and you what to usertag it, you can add these
lines (in the pseudo-header)

User: <user email address>
Usertags: <tag>

right after

Package: <package>
Version: <version>
Severity: <severity>

lines in the bug body.

Please note that if you specify more than 2 tag, then they will be
ordered alphabetically (so if you use usercategories, it will only
appears in the first one).

Thanks to: Sandro Tosi <morph@debian.org>

How to Use New GTK+ User Interface
==================================

If you tried to set the new GTK+ UI (named in reportbug as gtk2 ui)
and it fails to start (falling back to text mode, hopefully), chances
are that you are missing some of the needed modules:

 - python-gtk2
 - python-vte

If after installing both of them still GTK+ UI doesn't show up, please
file a report (in text ui :) ).

Thanks to: Sandro Tosi <morph@debian.org>

How to Use `gnus` MUA effectively
=================================

reportbug is now able to use an already running instance of emacs,
instead of spawning a new one.

In order to obtain that, you have to install:

- `emacs22-bin-common` or `emacs23-bin-common` (as mentioned in
  Suggests control field)

that contains the `emacsclient` program needed for the integration to
work (minimum version is 22 because earlier versions of `emacsclient`
did not support the `--eval` option).

Then a change to ~/.emacs file is needed, in order to add:

  (server-start)

or else Emacs won't listen for connections from emacsclient (and a new
`emacs` instance is executed).

With this changes, using the `gnus` MUA, the mail is opened in the
running `emacs`, or if there's none, a new instance is executed.

Thanks to: Håkon Stordahl <hakon@stordahl.org>

How To Specify Pseudo-Headers
=============================

A pseudo-header is like a mail header (a pair of '<field>: value') but specified
at the beginning of the mail body, instead of in the mail headers section.

Some pseudo-headers, like 'Version' or 'Package' are added automatically by
reportbug when preparing the report, but others can be specified by the
reporter.

This can be achieved in two ways:

 - from the command-line, using "-P '<field>: value'" command-line option;
 - directly when writing the report, appending the pseudo-header to the list at
   the beginning of the email body.

First of all, please note that reportbug tries to recognize if a given header is
a pseudo-header, and so it should be left in the pseudo-header list, or else
it's a mail header, and so it should be moved into mail headers section. This is
done because it's easier to add a mail header to the pseudo-header list (because
it's in the mail body, so you don't have to edit the mail headers) and let
reportbug move it (or leave it) to the correct location (for example,
'X-Debbugs-Cc' if added to the pseudo-header is then moved to mail headers
section to be processed by debbugs engine).

That said, please note that this two ways have now a different semantics: any
pseudo-header passed on the command-line is preserved as a pseudo-header, and
not moved to the mail headers part of the email, while adding a header into the
mail body still trigger the reportbug recognition code that will move the header
to mail headers part if not a "common" pseudo-header (like 'Usertags',
'Severity', or 'Package' and so on).

Network Errors and Timeout
==========================

There are situations where a network error is returned, for example:
"Unable to connect to BTS". These of course can be caused by a network
unavailability.

Another explanation can be that the remote resource is so slow to
respond (or it's stale) and a timeout is triggered. By default this
timeout is set to 1 minute; so in case of such an error, if you're
unsure that it's a clear network outage, you can try to pass
`--timeout <secs>' to either `reportbug' or `querybts' and see if it
solves the issue.

reportbug.debian.org SMTP Host Service Usage Policy
===================================================

Since Dec 2008 (see NEWS entry about it), the Debian project provides
a convenient SMTP host specifically aimed for reportbug:
reportbug.debian.org.

This host is useful in situations like:

 - the machine doesn't have a local MTA to forward emails;
 - no SMTP server is known;
 - the usual SMTP server is not working/unusable (different network);
 - etc.

Please keep in mind that this service has some limitations:

 - only 5 reports per hour are allowed (technically, 5 connections to
   the server, even if they don't result in bugs submission);
 - relay is not allowed.

The last rule, in particular, doesn't allow to send a carbon-copy of
the report to the submitter (the same email sent to the BTS to open
the bug), and X-Debbugs-CC has to be used instead (that will send an
email after BTS processing).

Let us also clarify that this service is in no way controlled by
reportbug maintainers, so in case any questions/complains/information
requests you have to contact owner@bugs.debian.org .