feedback.but

putty

\define{versionidfeedback} \versionid $Id: feedback.but 6895 2006-11-08 21:15:30Z jacob $

\A{feedback} \ii{Feedback} and \i{bug reporting}

This is a guide to providing feedback to the PuTTY development team.
It is provided as both a web page on the PuTTY site, and an appendix
in the PuTTY manual.

\K{feedback-general} gives some general guidelines for sending any
kind of e-mail to the development team. Following sections give more
specific guidelines for particular types of e-mail, such as bug
reports and feature requests.

\H{feedback-general} General guidelines

The PuTTY development team gets a \e{lot} of mail. If you can
possibly solve your own problem by reading the manual, reading the
FAQ, reading the web site, asking a fellow user, perhaps posting to a
newsgroup (see \k{feedback-other-fora}), or some other means, then it
would make our lives much easier.

We get so much e-mail that we literally do not have time to answer
it all. We regret this, but there's nothing we can do about it. So
if you can \e{possibly} avoid sending mail to the PuTTY team, we
recommend you do so. In particular, support requests
(\k{feedback-support}) are probably better sent to newsgroups, or
passed to a local expert if possible.

The PuTTY contact email address is a private \i{mailing list} containing
four or five core developers. Don't be put off by it being a mailing
list: if you need to send confidential data as part of a bug report,
you can trust the people on the list to respect that confidence.
Also, the archives aren't publicly available, so you shouldn't be
letting yourself in for any spam by sending us mail.

Please use a meaningful subject line on your message.  We get a lot of
mail, and it's hard to find the message we're looking for if they all
have subject lines like \q{PuTTY bug}.

\S{feedback-largefiles} Sending large attachments

Since the PuTTY contact address is a mailing list, e-mails larger
than 40Kb will be held for inspection by the list administrator, and
will not be allowed through unless they really appear to be worth
their large size.

If you are considering sending any kind of large data file to the
PuTTY team, it's almost always a bad idea, or at the very least it
would be better to ask us first whether we actually need the file.
Alternatively, you could put the file on a web site and just send us
the URL; that way, we don't have to download it unless we decide we
actually need it, and only one of us needs to download it instead of
it being automatically copied to all the developers.

Some people like to send mail in MS Word format. Please \e{don't}
send us bug reports, or any other mail, as a Word document. Word
documents are roughly fifty times larger than writing the same
report in plain text. In addition, most of the PuTTY team read their
e-mail on Unix machines, so copying the file to a Windows box to run
Word is very inconvenient. Not only that, but several of us don't
even \e{have} a copy of Word!

Some people like to send us screen shots when demonstrating a
problem. Please don't do this without checking with us first - we
almost never actually need the information in the screen shot.
Sending a screen shot of an error box is almost certainly
unnecessary when you could just tell us in plain text what the error
was. (On some versions of Windows, pressing Ctrl-C when the error
box is displayed will copy the text of the message to the clipboard.)
Sending a full-screen shot is \e{occasionally} useful, but it's
probably still wise to check whether we need it before sending it.

If you \e{must} mail a screen shot, don't send it as a \cw{.BMP}
file. \cw{BMP}s have no compression and they are \e{much} larger
than other image formats such as PNG, TIFF and GIF. Convert the file
to a properly compressed image format before sending it.

Please don't mail us executables, at all. Our mail server blocks all
incoming e-mail containing executables, as a defence against the
vast numbers of e-mail viruses we receive every day. If you mail us
an executable, it will just bounce.

If you have made a tiny modification to the PuTTY code, please send
us a \e{patch} to the source code if possible, rather than sending
us a huge \cw{.ZIP} file containing the complete sources plus your
modification. If you've only changed 10 lines, we'd prefer to
receive a mail that's 30 lines long than one containing multiple
megabytes of data we already have.

\S{feedback-other-fora} Other places to ask for help

There are two Usenet newsgroups that are particularly relevant to the
PuTTY tools:

\b \W{news:comp.security.ssh}\c{comp.security.ssh}, for questions
specific to using the SSH protocol;

\b \W{news:comp.terminals}\c{comp.terminals}, for issues relating to
terminal emulation (for instance, keyboard problems).

Please use the newsgroup most appropriate to your query, and remember
that these are general newsgroups, not specifically about PuTTY.

If you don't have direct access to Usenet, you can access these
newsgroups through Google Groups
(\W{http://groups.google.com/}\cw{groups.google.com}).

\H{feedback-bugs} Reporting bugs

If you think you have found a bug in PuTTY, your first steps should
be:

\b Check the
\W{http://www.chiark.greenend.org.uk/~sgtatham/putty/wishlist/}{Wishlist
page} on the PuTTY website, and see if we already know about the
problem. If we do, it is almost certainly not necessary to mail us
about it, unless you think you have extra information that might be
helpful to us in fixing it. (Of course, if we actually \e{need}
specific extra information about a particular bug, the Wishlist page
will say so.)

\b Check the
\W{http://www.chiark.greenend.org.uk/~sgtatham/putty/changes.html}{Change
Log} on the PuTTY website, and see if we have already fixed the bug
in the \i{development snapshots}.

\b Check the
\W{http://www.chiark.greenend.org.uk/~sgtatham/putty/faq.html}{FAQ}
on the PuTTY website (also provided as \k{faq} in the manual), and
see if it answers your question. The FAQ lists the most common
things which people think are bugs, but which aren't bugs.

\b Download the latest development snapshot and see if the problem
still happens with that. This really is worth doing. As a general
rule we aren't very interested in bugs that appear in the release
version but not in the development version, because that usually
means they are bugs we have \e{already fixed}. On the other hand, if
you can find a bug in the development version that doesn't appear in
the release, that's likely to be a new bug we've introduced since
the release and we're definitely interested in it.

If none of those options solved your problem, and you still need to
report a bug to us, it is useful if you include some general
information:

\b Tell us what \i{version of PuTTY} you are running. To find this out,
use the \q{About PuTTY} option from the System menu. Please \e{do
not} just tell us \q{I'm running the latest version}; e-mail can be
delayed and it may not be obvious which version was the latest at
the time you sent the message. 

\b PuTTY is a multi-platform application; tell us what version of what
OS you are running PuTTY on. (If you're running on Unix, or Windows
for Alpha, tell us, or we'll assume you're running on Windows for
Intel as this is overwhelmingly the case.)

\b Tell us what protocol you are connecting with: SSH, Telnet,
Rlogin or Raw mode.

\b Tell us what kind of server you are connecting to; what OS, and
if possible what SSH server (if you're using SSH). You can get some
of this information from the PuTTY Event Log (see \k{using-eventlog}
in the manual).

\b Send us the contents of the PuTTY Event Log, unless you
have a specific reason not to (for example, if it contains
confidential information that you think we should be able to solve
your problem without needing to know).

\b Try to give us as much information as you can to help us
see the problem for ourselves. If possible, give us a step-by-step
sequence of \e{precise} instructions for reproducing the fault.

\b Don't just tell us that PuTTY \q{does the wrong thing}; tell us
exactly and precisely what it did, and also tell us exactly and
precisely what you think it should have done instead. Some people
tell us PuTTY does the wrong thing, and it turns out that it was
doing the right thing and their expectations were wrong. Help to
avoid this problem by telling us exactly what you think it should
have done, and exactly what it did do.

\b If you think you can, you're welcome to try to fix the problem
yourself. A \i{patch} to the code which fixes a bug is an excellent
addition to a bug report. However, a patch is never a \e{substitute}
for a good bug report; if your patch is wrong or inappropriate, and
you haven't supplied us with full information about the actual bug,
then we won't be able to find a better solution.

\b
\W{http://www.chiark.greenend.org.uk/~sgtatham/bugs.html}\cw{http://www.chiark.greenend.org.uk/~sgtatham/bugs.html}
is an article on how to report bugs effectively in general. If your
bug report is \e{particularly} unclear, we may ask you to go away,
read this article, and then report the bug again.

It is reasonable to report bugs in PuTTY's documentation, if you
think the documentation is unclear or unhelpful. But we do need to
be given exact details of \e{what} you think the documentation has
failed to tell you, or \e{how} you think it could be made clearer.
If your problem is simply that you don't \e{understand} the
documentation, we suggest posting to a newsgroup (see
\k{feedback-other-fora}) and seeing if someone
will explain what you need to know. \e{Then}, if you think the
documentation could usefully have told you that, send us a bug
report and explain how you think we should change it.

\H{feedback-features} Requesting extra features 

If you want to request a new feature in PuTTY, the very first things