1 \versionid $Id: feedback.but,v 1.4 2002/04/27 16:20:16 simon Exp $
3 \A{feedback} Feedback and bug reporting
5 This is a guide to providing feedback to the PuTTY development team.
6 It is provided as both a web page on the PuTTY site, and an appendix
9 \K{feedback-general} gives some general guidelines for sending any
10 kind of e-mail to the development team. Following sections give more
11 specific guidelines for particular types of e-mail, such as bug
12 reports and feature requests.
14 \H{feedback-general} General guidelines
16 The PuTTY development team gets a \e{lot} of mail. If you can
17 possibly solve your own problem by reading the manual, reading the
18 FAQ, reading the web site, asking a fellow user, perhaps posting on
19 the newsgroup \W{news:comp.security.ssh}\c{comp.security.ssh}, or
20 some other means, then it would make our lives much easier.
22 We get so much e-mail that we literally do not have time to answer
23 it all. We regret this, but there's nothing we can do about it. So
24 if you can \e{possibly} avoid sending mail to the PuTTY team, we
25 recommend you do so. In particular, support requests
26 (\k{feedback-support}) are probably better sent to
27 \W{news:comp.security.ssh}\c{comp.security.ssh} or passed to a local
30 The PuTTY contact email address is a mailing list. For this reason,
31 e-mails larger than 40Kb will be held for inspection by the list
32 administrator, and will not be allowed through unless they really
33 appear to be worth their large size. Therefore:
35 \b Don't send your bug report as a Word document. Word documents are
36 roughly fifty times larger than writing the same report in plain
37 text. In addition, most of the PuTTY team read their e-mail on Unix
38 machines, so copying the attachment to a Windows box to run Word is
39 very inconvenient. Not only that, but several of us don't even
40 \e{have} a copy of Word!
42 \b Don't mail large screen shots without checking with us first.
43 Sending a screen shot of an error box is almost certainly
44 unnecessary when you could just tell us in plain text what the error
45 was. Sending a full-screen shot is sometimes useful, but it's
46 probably still wise to check with us before sending it.
48 \b If you want to send us a screen shot, or any other kind of large
49 data file, it is much more convenient for us if you can put the file
50 on a web site and send us the URL. That way (a) we don't have to
51 download it at all if it doesn't look necessary; and (b) only one
52 member of the team needs to download it, instead of it being
53 automatically sent to everyone on the mailing list.
55 \b If you \e{must} mail a screen shot, don't send it as a \cw{.BMP}
56 file. \cw{BMP}s have no compression and they are \e{much} larger
57 than other image formats such as PNG, TIFF and GIF. Convert the file
58 to a properly compressed image format before sending it.
60 (Note that although the PuTTY contact address is a mailing list, the
61 archives aren't publicly available, so you shouldn't be letting
62 yourself in for any spam by sending us mail.)
64 \H{feedback-bugs} Reporting bugs
66 If you think you have found a bug in PuTTY, your first steps should
70 \W{http://www.chiark.greenend.org.uk/~sgtatham/putty/wishlist.html}{Wishlist
71 page} on the PuTTY website, and see if we already know about the
72 problem. If we do, it is almost certainly not necessary to mail us
73 about it, unless you think you have extra information that might be
74 helpful to us in fixing it. (Of course, if we actually \e{need}
75 specific extra information about a particular bug, the Wishlist page
79 \W{http://www.chiark.greenend.org.uk/~sgtatham/putty/changes.html}{Change
80 Log} on the PuTTY website, and see if we have already fixed the bug
81 in the development snapshots.
84 \W{http://www.chiark.greenend.org.uk/~sgtatham/putty/faq.html}{FAQ}
85 on the PuTTY website (also provided as \k{faq} in the manual), and
86 see if it answers your question. The FAQ lists the most common
87 things which people think are bugs, but which aren't bugs.
89 \b Download the latest development snapshot and see if the problem
90 still happens with that. This really is worth doing. As a general
91 rule we aren't very interested in bugs that appear in the release
92 version but not in the development version, because that usually
93 means they are bugs we have \e{already fixed}. On the other hand, if
94 you can find a bug in the development version that doesn't appear in
95 the release, that's likely to be a new bug we've introduced since
96 the release and we're definitely interested in it.
98 If none of those options solved your problem, and you still need to
99 report a bug to us, it is useful if you include some general
102 \b Tell us what version of PuTTY you are running. To find this out,
103 use the "About PuTTY" option from the System menu. Please \e{do not}
104 just tell us \q{I'm running the latest version}; e-mail can be
105 delayed and it may not be obvious which version was the latest at
106 the time you sent the message.
108 \b Tell us what version of what OS you are running PuTTY on.
110 \b Tell us what protocol you are connecting with: SSH, Telnet,
113 \b Tell us what kind of server you are connecting to; what OS, and
114 if possible what SSH server (if you're using SSH). You can get some
115 of this information from the PuTTY Event Log (see \k{using-eventlog}
118 \b Send us the contents of the PuTTY Event Log, unless you
119 have a specific reason not to (for example, if it contains
120 confidential information that you think we should be able to solve
121 your problem without needing to know).
123 \b Try to give us as much information as you can to help us
124 see the problem for ourselves. If possible, give us a step-by-step
125 sequence of \e{precise} instructions for reproducing the fault.
127 \b Don't just tell us that PuTTY \q{does the wrong thing}; tell us
128 exactly and precisely what it did, and also tell us exactly and
129 precisely what you think it should have done instead. Some people
130 tell us PuTTY does the wrong thing, and it turns out that it was
131 doing the right thing and their expectations were wrong. Help to
132 avoid this problem by telling us exactly what you think it should
133 have done, and exactly what it did do.
135 \b If you think you can, you're welcome to try to fix the problem
136 yourself. A patch to the code which fixes a bug is an excellent
137 addition to a bug report. However, a patch is never a \e{substitute}
138 for a good bug report; if your patch is wrong or inappropriate, and
139 you haven't supplied us with full information about the actual bug,
140 then we won't be able to find a better solution.
143 \W{http://www.chiark.greenend.org.uk/~sgtatham/bugs.html}\cw{http://www.chiark.greenend.org.uk/~sgtatham/bugs.html}
144 is an article on how to report bugs effectively in general. If your
145 bug report is \e{particularly} unclear, we may ask you to go away,
146 read this article, and then report the bug again.
148 It is reasonable to report bugs in PuTTY's documentation, if you
149 think the documentation is unclear or unhelpful. But we do need to
150 be given exact details of \e{what} you think the documentation has
151 failed to tell you, or \e{how} you think it could be made clearer.
152 If your problem is simply that you don't \e{understand} the
153 documentation, we suggest posting to the newsgroup
154 \W{news:comp.security.ssh}\c{comp.security.ssh} and see if someone
155 will explain what you need to know. \e{Then}, if you think the
156 documentation could usefully have told you that, send us a bug
157 report and explain how you think we should change it.
159 \H{feedback-features} Requesting extra features
161 If you want to request a new feature in PuTTY, the very first things
165 \W{http://www.chiark.greenend.org.uk/~sgtatham/putty/wishlist.html}{Wishlist
166 page} on the PuTTY website, and see if your feature is already on
167 the list. If it is, it probably won't achieve very much to repeat
168 the request. (But see \k{feedback-feature-priority} if you want to
169 persuade us to give your particular feature higher priority.)
172 \W{http://www.chiark.greenend.org.uk/~sgtatham/putty/changes.html}{Change
173 Log} on the PuTTY website, and see if we have already added your
174 feature in the development snapshots. If it isn't clear, download
175 the latest development snapshot and see if the feature is present.
176 If it is, then it will also be in the next release and there is no
177 need to mail us at all.
179 If you can't find your feature in either the development snapshots
180 \e{or} the Wishlist, then you probably do need to submit a feature
181 request. Since the PuTTY authors are very busy, it helps if you try
182 to do some of the work for us:
184 \b Do as much of the design as you can. Think about \q{corner
185 cases}; think about how your feature interacts with other existing
186 features. Think about the user interface; if you can't come up with
187 a simple and intuitive interface to your feature, you shouldn't be
188 surprised if we can't either. Always imagine whether it's possible
189 for there to be more than one, or less than one, of something you'd
190 assumed there would be one of. (For example, if you were to want
191 PuTTY to put an icon in the System tray rather than the Taskbar, you
192 should think about what happens if there's more than one PuTTY
193 active; how would the user tell which was which?)
195 \b If you can program, it may be worth offering to write the feature
196 yourself and send us a patch. However, it is likely to be helpful
197 if you confer with us first; there may be design issues you haven't
198 thought of, or we may be about to make big changes to the code which
199 your patch would clash with, or something. If you check with the
200 maintainers first, there is a better chance of your code actually
203 \H{feedback-feature-priority} Requesting features that have already
206 If a feature is already listed on the Wishlist, then it usually
207 means we would like to add it to PuTTY at some point. However, this
208 may not be in the near future. If there's a feature on the Wishlist
209 which you would like to see in the \e{near} future, there are
210 several things you can do to try to increase its priority level:
212 \b Mail us and vote for it. (Be sure to mention that you've seen it
213 on the Wishlist, or we might think you haven't even \e{read} the
214 Wishlist). This probably won't have very \e{much} effect; if a huge
215 number of people vote for something then it may make a difference,
216 but one or two extra votes for a particular feature are unlikely to
217 change our priority list immediately. Also, don't expect a reply.
219 \b Offer us money if we do the work sooner rather than later. This
220 sometimes works, but not always. The PuTTY team all have full-time
221 jobs and we're doing all of this work in our free time; we may
222 sometimes be willing to give up some more of our free time in
223 exchange for some money, but if you try to bribe us for a \e{big}
224 feature it's entirely possible that we simply won't have the time to
225 spare - whether you pay us or not. (Also, we don't accept bribes to
226 add \e{bad} features to the Wishlist, because our desire to provide
227 high-quality software to the users comes first.)
229 \b Offer to help us write the code. This is probably the \e{only}
230 way to get a feature implemented quickly, if it's a big one that we
231 don't have time to do ourselves.
233 \H{feedback-support} Support requests
235 If you're trying to make PuTTY do something for you and it isn't
236 working, but you're not sure whether it's a bug or not, then
237 \e{please} consider looking for help somewhere else. This is one of
238 the most common types of mail the PuTTY team receives, and we simply
239 don't have time to answer all the questions. Questions of this type
242 \b If you want to do something with PuTTY but have no idea where to
243 start, and reading the manual hasn't helped, try posting to the
244 newsgroup \W{news:comp.security.ssh}\c{comp.security.ssh} and see if
245 someone can explain it to you.
247 \b If you have tried to do something with PuTTY but it hasn't
248 worked, and you aren't sure whether it's a bug in PuTTY or a bug in
249 your SSH server or simply that you're not doing it right, then try
250 posting to \W{news:comp.security.ssh}\c{comp.security.ssh} and see
251 if someone can solve your problem. Or try doing the same thing with
252 a different SSH client and see if it works with that. Please do not
253 report it as a PuTTY bug unless you are really sure it \e{is} a bug
256 \b If you have successfully made a connection to your server and now
257 need to know what to type at the server's command prompt, or other
258 details of how to use the server-end software, talk to your server's
259 system administrator. This is not the PuTTY team's problem. PuTTY is
260 only a communications tool, like a telephone; if you can't speak the
261 same language as the person at the other end of the phone, it isn't
262 the telephone company's job to teach it to you.
264 If you absolutely cannot get a support question answered any other
265 way, you can try mailing it to us, but we can't guarantee to have
268 \H{feedback-webadmin} Web server administration
270 If the PuTTY web site is down (Connection Timed Out), please don't
271 bother mailing us to tell us about it. Most of us read our e-mail on
272 the same machines that host the web site, so if those machines are
273 down then we will notice \e{before} we read our e-mail. So there's
274 no point telling us our servers are down.
276 Of course, if the web site has some other error (Connection Refused,
277 404 Not Found, 403 Forbidden, or something else) then we might
278 \e{not} have noticed and it might still be worth telling us about it.
280 \H{feedback-permission} Asking permission for things
282 PuTTY is distributed under the MIT Licence (see \k{licence} for
283 details). This means you can do almost \e{anything} you like with
284 our software, our source code, and our documentation. The only
285 things you aren't allowed to do are to remove our copyright notices
286 or the licence text itself, or to hold us legally responsible if
287 something goes wrong.
289 So if you want permission to include PuTTY on a magazine cover disk,
290 or as part of a collection of useful software on a CD or a web site,
291 then \e{permission is already granted}. You don't have to mail us
292 and ask. Just go ahead and do it. We don't mind.
294 If you want to use parts of the PuTTY source code in another
295 program, then it might be worth mailing us to talk about technical
296 details, but if all you want is to ask permission then you don't
297 need to bother. You already have permission.
299 \H{feedback-mirrors} Mirroring the PuTTY web site
301 All mirrors of the PuTTY web site are welcome. Please don't bother
302 asking us for permission before setting up a mirror. You already
303 have permission. We are always happy to have more mirrors.
305 If you mail us \e{after} you have set up the mirror, and remember to
306 let us know which country your mirror is in, then we'll add it to
308 \W{http://www.chiark.greenend.org.uk/~sgtatham/putty/mirrors.html}{Mirrors
309 page} on the PuTTY website.
311 If you have technical questions about the process of mirroring, then
312 you might want to mail us before setting up the mirror; but if you
313 just want to ask for permission, you don't need to. You already have
316 \H{feedback-compliments} Praise and compliments
318 One of the most rewarding things about maintaining free software is
319 getting e-mails that just say \q{thanks}. We are always happy to
320 receive e-mails of this type.
322 Regrettably we don't have time to answer them all in person. If you
323 mail us a compliment and don't receive a reply, \e{please} don't
324 think we've ignored you. We did receive it and we were happy about
325 it; we just didn't have time to tell you so personally.
327 To everyone who's ever sent us praise and compliments, in the past
328 and the future: \e{you're welcome}!
330 \H{feedback-address} E-mail address
332 The actual address to mail is
333 \cw{<\W{mailto:putty@projects.tartarus.org}{putty@projects.tartarus.org}>}.