===============================
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 add Usertags to a Bug at Report Time
===========================================

If you're filing a bug and you want 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 tags, then they will be
ordered alphabetically (so if you use usercategories, it will only
appear in the first one).

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


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

If you tried to set the GTK+ UI (named in reportbug as gtk ui)
and it fails to start (falling back to text mode, hopefully), then
please install the reportbug-gtk package to get the needed dependencies.

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

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


Support for external MUAs
=========================

reportbug has limited support for external Mail User Agents (MUAs),
allowing you to pass the prepared report to your email client for
finalization and submission. This integration feature is somewhat
fragile and sometimes unreliable.

Use this at your own risk. You may lose your report if something fails!

Supported MUAs include: alpine, claws-mail, evolution, gnus, kmail,
neomutt, nmh, mh, mutt, pine, sylpheed, thunderbird, and xdg-email.
To configure reportbug to use your MUA of choice, place a line like
this in your $HOME/.reportbugrc:
    mua alpine

Not all MUAs are supported equally well. Known problems and
limitations include:

 - With many MUAs there is no feedback (via exitcode) to reportbug on
   whether the report was sent or not.

 - Passing desired attachments to the MUA does not work with all MUAs;
   you may have to attach everything (if needed) in the MUA itself.

 - Setting custom mail headers may only work in a few cases.

 - Long messages may be truncated.

One particularly unreliable choice is to specify `xdg-email' as your
MUA. It is not actually a MUA itself, but will try to automatically
detect and launch your preferred MUA. The frameworks it is relying upon
may even allow you to use a webmail service for report submission, so
this can be very convenient if you are used to using such a service.

The downside of xdg-email's flexibility is that it relies on a bunch of
external tools that can fail or exhibit unexpected behavior. You might
lose your report without ever even seeing any error message! Please test
this extensively before seriously using it. If you encounter any
problems, please report them to the appropriate package (belonging to
your Desktop Environment, or xdg-utils) and not to reportbug!


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 these 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.

That said, please note that these two ways have 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 triggers the reportbug recognition code that will move the header
to mail headers part if it is 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.

In order to configure reportbug to use it, run `reportbug --configure',
enter your name and email address where appropriate, and just press
Enter at all other prompts.

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 bug 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/complaints/information
requests you have to contact owner@bugs.debian.org .