39a938f7 |
1 | \define{versionidfeedback} \versionid $Id$ |
3c42d118 |
2 | |
421406a4 |
3 | \A{feedback} \ii{Feedback} and \i{bug reporting} |
3c42d118 |
4 | |
5179cf2d |
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 |
7 | in the PuTTY manual. |
3c42d118 |
8 | |
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. |
13 | |
14 | \H{feedback-general} General guidelines |
15 | |
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 |
87b461db |
18 | FAQ, reading the web site, asking a fellow user, perhaps posting to a |
19 | newsgroup (see \k{feedback-other-fora}), or some other means, then it |
20 | would make our lives much easier. |
3c42d118 |
21 | |
102e81cf |
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 |
87b461db |
26 | (\k{feedback-support}) are probably better sent to newsgroups, or |
27 | passed to a local expert if possible. |
3c42d118 |
28 | |
421406a4 |
29 | The PuTTY contact email address is a private \i{mailing list} containing |
c43991d1 |
30 | four or five core developers. Don't be put off by it being a mailing |
31 | list: if you need to send confidential data as part of a bug report, |
32 | you can trust the people on the list to respect that confidence. |
33 | Also, the archives aren't publicly available, so you shouldn't be |
34 | letting yourself in for any spam by sending us mail. |
3c42d118 |
35 | |
492a04db |
36 | Please use a meaningful subject line on your message. We get a lot of |
37 | mail, and it's hard to find the message we're looking for if they all |
38 | have subject lines like \q{PuTTY bug}. |
39 | |
c43991d1 |
40 | \S{feedback-largefiles} Sending large attachments |
3c42d118 |
41 | |
c43991d1 |
42 | Since the PuTTY contact address is a mailing list, e-mails larger |
43 | than 40Kb will be held for inspection by the list administrator, and |
44 | will not be allowed through unless they really appear to be worth |
45 | their large size. |
46 | |
47 | If you are considering sending any kind of large data file to the |
48 | PuTTY team, it's almost always a bad idea, or at the very least it |
49 | would be better to ask us first whether we actually need the file. |
50 | Alternatively, you could put the file on a web site and just send us |
51 | the URL; that way, we don't have to download it unless we decide we |
52 | actually need it, and only one of us needs to download it instead of |
53 | it being automatically copied to all the developers. |
54 | |
55 | Some people like to send mail in MS Word format. Please \e{don't} |
56 | send us bug reports, or any other mail, as a Word document. Word |
57 | documents are roughly fifty times larger than writing the same |
58 | report in plain text. In addition, most of the PuTTY team read their |
59 | e-mail on Unix machines, so copying the file to a Windows box to run |
60 | Word is very inconvenient. Not only that, but several of us don't |
61 | even \e{have} a copy of Word! |
62 | |
63 | Some people like to send us screen shots when demonstrating a |
64 | problem. Please don't do this without checking with us first - we |
65 | almost never actually need the information in the screen shot. |
3c42d118 |
66 | Sending a screen shot of an error box is almost certainly |
67 | unnecessary when you could just tell us in plain text what the error |
61017c33 |
68 | was. (On some versions of Windows, pressing Ctrl-C when the error |
69 | box is displayed will copy the text of the message to the clipboard.) |
70 | Sending a full-screen shot is \e{occasionally} useful, but it's |
c43991d1 |
71 | probably still wise to check whether we need it before sending it. |
3c42d118 |
72 | |
c43991d1 |
73 | If you \e{must} mail a screen shot, don't send it as a \cw{.BMP} |
3c42d118 |
74 | file. \cw{BMP}s have no compression and they are \e{much} larger |
75 | than other image formats such as PNG, TIFF and GIF. Convert the file |
76 | to a properly compressed image format before sending it. |
77 | |
55881b4f |
78 | Please don't mail us executables, at all. Our mail server blocks all |
79 | incoming e-mail containing executables, as a defence against the |
80 | vast numbers of e-mail viruses we receive every day. If you mail us |
81 | an executable, it will just bounce. |
c43991d1 |
82 | |
83 | If you have made a tiny modification to the PuTTY code, please send |
84 | us a \e{patch} to the source code if possible, rather than sending |
85 | us a huge \cw{.ZIP} file containing the complete sources plus your |
86 | modification. If you've only changed 10 lines, we'd prefer to |
87 | receive a mail that's 30 lines long than one containing multiple |
88 | megabytes of data we already have. |
3559b7b2 |
89 | |
87b461db |
90 | \S{feedback-other-fora} Other places to ask for help |
91 | |
92 | There are two Usenet newsgroups that are particularly relevant to the |
93 | PuTTY tools: |
94 | |
95 | \b \W{news:comp.security.ssh}\c{comp.security.ssh}, for questions |
96 | specific to using the SSH protocol; |
97 | |
98 | \b \W{news:comp.terminals}\c{comp.terminals}, for issues relating to |
99 | terminal emulation (for instance, keyboard problems). |
100 | |
b7f084e5 |
101 | Please use the newsgroup most appropriate to your query, and remember |
102 | that these are general newsgroups, not specifically about PuTTY. |
103 | |
87b461db |
104 | If you don't have direct access to Usenet, you can access these |
105 | newsgroups through Google Groups |
106 | (\W{http://groups.google.com/}\cw{groups.google.com}). |
107 | |
3c42d118 |
108 | \H{feedback-bugs} Reporting bugs |
109 | |
110 | If you think you have found a bug in PuTTY, your first steps should |
111 | be: |
112 | |
113 | \b Check the |
ebe9a956 |
114 | \W{http://www.chiark.greenend.org.uk/~sgtatham/putty/wishlist/}{Wishlist |
3c42d118 |
115 | page} on the PuTTY website, and see if we already know about the |
116 | problem. If we do, it is almost certainly not necessary to mail us |
117 | about it, unless you think you have extra information that might be |
118 | helpful to us in fixing it. (Of course, if we actually \e{need} |
119 | specific extra information about a particular bug, the Wishlist page |
120 | will say so.) |
121 | |
122 | \b Check the |
123 | \W{http://www.chiark.greenend.org.uk/~sgtatham/putty/changes.html}{Change |
124 | Log} on the PuTTY website, and see if we have already fixed the bug |
421406a4 |
125 | in the \i{development snapshots}. |
3c42d118 |
126 | |
127 | \b Check the |
128 | \W{http://www.chiark.greenend.org.uk/~sgtatham/putty/faq.html}{FAQ} |
129 | on the PuTTY website (also provided as \k{faq} in the manual), and |
130 | see if it answers your question. The FAQ lists the most common |
131 | things which people think are bugs, but which aren't bugs. |
132 | |
133 | \b Download the latest development snapshot and see if the problem |
134 | still happens with that. This really is worth doing. As a general |
135 | rule we aren't very interested in bugs that appear in the release |
136 | version but not in the development version, because that usually |
137 | means they are bugs we have \e{already fixed}. On the other hand, if |
138 | you can find a bug in the development version that doesn't appear in |
139 | the release, that's likely to be a new bug we've introduced since |
140 | the release and we're definitely interested in it. |
141 | |
142 | If none of those options solved your problem, and you still need to |
143 | report a bug to us, it is useful if you include some general |
144 | information: |
145 | |
421406a4 |
146 | \b Tell us what \i{version of PuTTY} you are running. To find this out, |
3a115fdd |
147 | use the \q{About PuTTY} option from the System menu. Please \e{do |
148 | not} just tell us \q{I'm running the latest version}; e-mail can be |
3c42d118 |
149 | delayed and it may not be obvious which version was the latest at |
150 | the time you sent the message. |
151 | |
a9c623ca |
152 | \b PuTTY is a multi-platform application; tell us what version of what |
153 | OS you are running PuTTY on. (If you're running on Unix, or Windows |
154 | for Alpha, tell us, or we'll assume you're running on Windows for |
155 | Intel as this is overwhelmingly the case.) |
3c42d118 |
156 | |
157 | \b Tell us what protocol you are connecting with: SSH, Telnet, |
158 | Rlogin or Raw mode. |
159 | |
160 | \b Tell us what kind of server you are connecting to; what OS, and |
161 | if possible what SSH server (if you're using SSH). You can get some |
162 | of this information from the PuTTY Event Log (see \k{using-eventlog} |
163 | in the manual). |
164 | |
165 | \b Send us the contents of the PuTTY Event Log, unless you |
166 | have a specific reason not to (for example, if it contains |
167 | confidential information that you think we should be able to solve |
168 | your problem without needing to know). |
169 | |
170 | \b Try to give us as much information as you can to help us |
171 | see the problem for ourselves. If possible, give us a step-by-step |
172 | sequence of \e{precise} instructions for reproducing the fault. |
173 | |
174 | \b Don't just tell us that PuTTY \q{does the wrong thing}; tell us |
175 | exactly and precisely what it did, and also tell us exactly and |
176 | precisely what you think it should have done instead. Some people |
177 | tell us PuTTY does the wrong thing, and it turns out that it was |
178 | doing the right thing and their expectations were wrong. Help to |
179 | avoid this problem by telling us exactly what you think it should |
180 | have done, and exactly what it did do. |
181 | |
182 | \b If you think you can, you're welcome to try to fix the problem |
421406a4 |
183 | yourself. A \i{patch} to the code which fixes a bug is an excellent |
3c42d118 |
184 | addition to a bug report. However, a patch is never a \e{substitute} |
185 | for a good bug report; if your patch is wrong or inappropriate, and |
186 | you haven't supplied us with full information about the actual bug, |
187 | then we won't be able to find a better solution. |
188 | |
189 | \b |
190 | \W{http://www.chiark.greenend.org.uk/~sgtatham/bugs.html}\cw{http://www.chiark.greenend.org.uk/~sgtatham/bugs.html} |
191 | is an article on how to report bugs effectively in general. If your |
192 | bug report is \e{particularly} unclear, we may ask you to go away, |
193 | read this article, and then report the bug again. |
194 | |
102e81cf |
195 | It is reasonable to report bugs in PuTTY's documentation, if you |
196 | think the documentation is unclear or unhelpful. But we do need to |
197 | be given exact details of \e{what} you think the documentation has |
198 | failed to tell you, or \e{how} you think it could be made clearer. |
199 | If your problem is simply that you don't \e{understand} the |
87b461db |
200 | documentation, we suggest posting to a newsgroup (see |
201 | \k{feedback-other-fora}) and seeing if someone |
102e81cf |
202 | will explain what you need to know. \e{Then}, if you think the |
203 | documentation could usefully have told you that, send us a bug |
204 | report and explain how you think we should change it. |
205 | |
3c42d118 |
206 | \H{feedback-features} Requesting extra features |
207 | |
208 | If you want to request a new feature in PuTTY, the very first things |
209 | you should do are: |
210 | |
211 | \b Check the |
ebe9a956 |
212 | \W{http://www.chiark.greenend.org.uk/~sgtatham/putty/wishlist/}{Wishlist |
3c42d118 |
213 | page} on the PuTTY website, and see if your feature is already on |
214 | the list. If it is, it probably won't achieve very much to repeat |
215 | the request. (But see \k{feedback-feature-priority} if you want to |
216 | persuade us to give your particular feature higher priority.) |
217 | |
46030c4c |
218 | \b Check the Wishlist and |
3c42d118 |
219 | \W{http://www.chiark.greenend.org.uk/~sgtatham/putty/changes.html}{Change |
220 | Log} on the PuTTY website, and see if we have already added your |
221 | feature in the development snapshots. If it isn't clear, download |
222 | the latest development snapshot and see if the feature is present. |
223 | If it is, then it will also be in the next release and there is no |
224 | need to mail us at all. |
225 | |
226 | If you can't find your feature in either the development snapshots |
227 | \e{or} the Wishlist, then you probably do need to submit a feature |
228 | request. Since the PuTTY authors are very busy, it helps if you try |
229 | to do some of the work for us: |
230 | |
231 | \b Do as much of the design as you can. Think about \q{corner |
232 | cases}; think about how your feature interacts with other existing |
233 | features. Think about the user interface; if you can't come up with |
234 | a simple and intuitive interface to your feature, you shouldn't be |
235 | surprised if we can't either. Always imagine whether it's possible |
236 | for there to be more than one, or less than one, of something you'd |
237 | assumed there would be one of. (For example, if you were to want |
238 | PuTTY to put an icon in the System tray rather than the Taskbar, you |
239 | should think about what happens if there's more than one PuTTY |
240 | active; how would the user tell which was which?) |
241 | |
242 | \b If you can program, it may be worth offering to write the feature |
243 | yourself and send us a patch. However, it is likely to be helpful |
244 | if you confer with us first; there may be design issues you haven't |
245 | thought of, or we may be about to make big changes to the code which |
246 | your patch would clash with, or something. If you check with the |
247 | maintainers first, there is a better chance of your code actually |
6f3bdded |
248 | being usable. Also, read the design principles listed in \k{udp}: if |
249 | you do not conform to them, we will probably not be able to accept |
250 | your patch. |
3c42d118 |
251 | |
252 | \H{feedback-feature-priority} Requesting features that have already |
253 | been requested |
254 | |
255 | If a feature is already listed on the Wishlist, then it usually |
256 | means we would like to add it to PuTTY at some point. However, this |
257 | may not be in the near future. If there's a feature on the Wishlist |
258 | which you would like to see in the \e{near} future, there are |
259 | several things you can do to try to increase its priority level: |
260 | |
261 | \b Mail us and vote for it. (Be sure to mention that you've seen it |
262 | on the Wishlist, or we might think you haven't even \e{read} the |
263 | Wishlist). This probably won't have very \e{much} effect; if a huge |
264 | number of people vote for something then it may make a difference, |
265 | but one or two extra votes for a particular feature are unlikely to |
1dcc27c8 |
266 | change our priority list immediately. Offering a new and compelling |
267 | justification might help. Also, don't expect a reply. |
3c42d118 |
268 | |
269 | \b Offer us money if we do the work sooner rather than later. This |
270 | sometimes works, but not always. The PuTTY team all have full-time |
271 | jobs and we're doing all of this work in our free time; we may |
272 | sometimes be willing to give up some more of our free time in |
273 | exchange for some money, but if you try to bribe us for a \e{big} |
274 | feature it's entirely possible that we simply won't have the time to |
275 | spare - whether you pay us or not. (Also, we don't accept bribes to |
276 | add \e{bad} features to the Wishlist, because our desire to provide |
277 | high-quality software to the users comes first.) |
278 | |
279 | \b Offer to help us write the code. This is probably the \e{only} |
280 | way to get a feature implemented quickly, if it's a big one that we |
281 | don't have time to do ourselves. |
282 | |
421406a4 |
283 | \H{feedback-support} \ii{Support requests} |
102e81cf |
284 | |
285 | If you're trying to make PuTTY do something for you and it isn't |
286 | working, but you're not sure whether it's a bug or not, then |
287 | \e{please} consider looking for help somewhere else. This is one of |
288 | the most common types of mail the PuTTY team receives, and we simply |
289 | don't have time to answer all the questions. Questions of this type |
290 | include: |
291 | |
292 | \b If you want to do something with PuTTY but have no idea where to |
87b461db |
293 | start, and reading the manual hasn't helped, try posting to a |
294 | newsgroup (see \k{feedback-other-fora}) and see if someone can explain |
295 | it to you. |
102e81cf |
296 | |
297 | \b If you have tried to do something with PuTTY but it hasn't |
298 | worked, and you aren't sure whether it's a bug in PuTTY or a bug in |
299 | your SSH server or simply that you're not doing it right, then try |
87b461db |
300 | posting to a newsgroup (see \k{feedback-other-fora}) and see |
102e81cf |
301 | if someone can solve your problem. Or try doing the same thing with |
302 | a different SSH client and see if it works with that. Please do not |
303 | report it as a PuTTY bug unless you are really sure it \e{is} a bug |
304 | in PuTTY. |
305 | |
0b375b66 |
306 | \b If someone else installed PuTTY for you, or you're using PuTTY on |
307 | someone else's computer, try asking them for help first. They're more |
308 | likely to understand how they installed it and what they expected you |
309 | to use it for than we are. |
310 | |
102e81cf |
311 | \b If you have successfully made a connection to your server and now |
312 | need to know what to type at the server's command prompt, or other |
313 | details of how to use the server-end software, talk to your server's |
314 | system administrator. This is not the PuTTY team's problem. PuTTY is |
315 | only a communications tool, like a telephone; if you can't speak the |
316 | same language as the person at the other end of the phone, it isn't |
317 | the telephone company's job to teach it to you. |
318 | |
319 | If you absolutely cannot get a support question answered any other |
320 | way, you can try mailing it to us, but we can't guarantee to have |
321 | time to answer it. |
322 | |
3c42d118 |
323 | \H{feedback-webadmin} Web server administration |
324 | |
421406a4 |
325 | If the PuTTY \i{web site} is down (Connection Timed Out), please don't |
3c42d118 |
326 | bother mailing us to tell us about it. Most of us read our e-mail on |
327 | the same machines that host the web site, so if those machines are |
328 | down then we will notice \e{before} we read our e-mail. So there's |
329 | no point telling us our servers are down. |
330 | |
331 | Of course, if the web site has some other error (Connection Refused, |
332 | 404 Not Found, 403 Forbidden, or something else) then we might |
333 | \e{not} have noticed and it might still be worth telling us about it. |
334 | |
3a66e913 |
335 | If you want to report a problem with our web site, check that you're |
336 | looking at our \e{real} web site and not a mirror. The real web site |
8a6c2751 |
337 | is at |
338 | \W{http://www.chiark.greenend.org.uk/~sgtatham/putty/}\c{http://www.chiark.greenend.org.uk/~sgtatham/putty/}; |
339 | if that's not where you're reading this, then don't report the |
340 | problem to us until you've checked that it's really a problem with |
341 | the main site. If it's only a problem with the mirror, you should |
342 | try to contact the administrator of that mirror site first, and only |
3a66e913 |
343 | contact us if that doesn't solve the problem (in case we need to |
344 | remove the mirror from our list). |
345 | |
3c42d118 |
346 | \H{feedback-permission} Asking permission for things |
347 | |
348 | PuTTY is distributed under the MIT Licence (see \k{licence} for |
349 | details). This means you can do almost \e{anything} you like with |
350 | our software, our source code, and our documentation. The only |
351 | things you aren't allowed to do are to remove our copyright notices |
352 | or the licence text itself, or to hold us legally responsible if |
353 | something goes wrong. |
354 | |
355 | So if you want permission to include PuTTY on a magazine cover disk, |
356 | or as part of a collection of useful software on a CD or a web site, |
357 | then \e{permission is already granted}. You don't have to mail us |
358 | and ask. Just go ahead and do it. We don't mind. |
359 | |
150ef9c6 |
360 | (If you want to distribute PuTTY alongside your own application for |
361 | use with that application, or if you want to distribute PuTTY within |
30a6b820 |
362 | your own organisation, then we recommend, but do not insist, that |
363 | you offer your own first-line technical support, to answer questions |
364 | about the interaction of PuTTY with your environment. If your users |
365 | mail us directly, we won't be able to tell them anything useful about |
366 | your specific setup.) |
150ef9c6 |
367 | |
3c42d118 |
368 | If you want to use parts of the PuTTY source code in another |
369 | program, then it might be worth mailing us to talk about technical |
370 | details, but if all you want is to ask permission then you don't |
371 | need to bother. You already have permission. |
372 | |
30a6b820 |
373 | If you just want to link to our web site, just go ahead. (It's not |
374 | clear that we \e{could} stop you doing this, even if we wanted to!) |
375 | |
3c42d118 |
376 | \H{feedback-mirrors} Mirroring the PuTTY web site |
377 | |
422f05f3 |
378 | \#{This paragraph also in putty-website/mirrors.html} |
9234175a |
379 | Mirrors of the PuTTY web site are welcome, especially in regions not |
422f05f3 |
380 | well covered by existing mirrors. (However, if you're in a region that is |
381 | already well served by mirrors, you should consider whether yet another one |
382 | will be worth the effort.) Please don't bother asking us for permission before |
383 | setting up a mirror. You already have permission. |
3c42d118 |
384 | |
211d84da |
385 | If you mail us \e{after} you have set up the mirror and checked that |
386 | it works, and remember to let us know which country your mirror is in, |
387 | then we'll add it to the |
3c42d118 |
388 | \W{http://www.chiark.greenend.org.uk/~sgtatham/putty/mirrors.html}{Mirrors |
389 | page} on the PuTTY website. |
390 | |
391 | If you have technical questions about the process of mirroring, then |
211d84da |
392 | you might want to mail us before setting up the mirror (see also the |
393 | \W{http://www.chiark.greenend.org.uk/~sgtatham/putty/mirrors.html#guidelines}{guidelines on the Mirrors page}); |
394 | but if you just want to ask for permission, you don't need to. You |
395 | already have permission. |
3c42d118 |
396 | |
397 | \H{feedback-compliments} Praise and compliments |
398 | |
399 | One of the most rewarding things about maintaining free software is |
400 | getting e-mails that just say \q{thanks}. We are always happy to |
401 | receive e-mails of this type. |
402 | |
403 | Regrettably we don't have time to answer them all in person. If you |
404 | mail us a compliment and don't receive a reply, \e{please} don't |
405 | think we've ignored you. We did receive it and we were happy about |
406 | it; we just didn't have time to tell you so personally. |
407 | |
408 | To everyone who's ever sent us praise and compliments, in the past |
409 | and the future: \e{you're welcome}! |
410 | |
411 | \H{feedback-address} E-mail address |
412 | |
413 | The actual address to mail is |
414 | \cw{<\W{mailto:putty@projects.tartarus.org}{putty@projects.tartarus.org}>}. |