| 1 | \versionid $Id: feedback.but,v 1.2 2001/12/16 15:14:36 simon Exp $ |
| 2 | |
| 3 | \A{feedback} Feedback and bug reporting |
| 4 | |
| 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. |
| 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 |
| 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. |
| 21 | |
| 22 | If the volume of e-mail really gets on top of us and we can't find |
| 23 | time to answer it all, then the first e-mails we discard will be the |
| 24 | ones from people who don't look as if they have made a reasonable |
| 25 | effort to solve their own problems. This is not intended to cause |
| 26 | offence; it's occasionally a necessary response to a serious |
| 27 | problem. We get a \e{lot} of e-mail. Really. |
| 28 | |
| 29 | Also, the PuTTY contact email address is a mailing list. For this |
| 30 | reason, e-mails larger than 40Kb will be held for inspection by the |
| 31 | list administrator, and will not be allowed through unless they |
| 32 | really appear to be worth their large size. Therefore: |
| 33 | |
| 34 | \b Don't send your bug report as a Word document. Word documents are |
| 35 | roughly fifty times larger than writing the same report in plain |
| 36 | text. In addition, most of the PuTTY team read their e-mail on Unix |
| 37 | machines, so copying the attachment to a Windows box to run Word is |
| 38 | very inconvenient. Not only that, but several of us don't even |
| 39 | \e{have} a copy of Word! |
| 40 | |
| 41 | \b Don't mail large screen shots without checking with us first. |
| 42 | Sending a screen shot of an error box is almost certainly |
| 43 | unnecessary when you could just tell us in plain text what the error |
| 44 | was. Sending a full-screen shot is sometimes useful, but it's |
| 45 | probably still wise to check with us before sending it. |
| 46 | |
| 47 | \b If you want to send us a screen shot, or any other kind of large |
| 48 | data file, it is much more convenient for us if you can put the file |
| 49 | on a web site and send us the URL. That way (a) we don't have to |
| 50 | download it at all if it doesn't look necessary; and (b) only one |
| 51 | member of the team needs to download it, instead of it being |
| 52 | automatically sent to everyone on the mailing list. |
| 53 | |
| 54 | \b If you \e{must} mail a screen shot, don't send it as a \cw{.BMP} |
| 55 | file. \cw{BMP}s have no compression and they are \e{much} larger |
| 56 | than other image formats such as PNG, TIFF and GIF. Convert the file |
| 57 | to a properly compressed image format before sending it. |
| 58 | |
| 59 | \H{feedback-bugs} Reporting bugs |
| 60 | |
| 61 | If you think you have found a bug in PuTTY, your first steps should |
| 62 | be: |
| 63 | |
| 64 | \b Check the |
| 65 | \W{http://www.chiark.greenend.org.uk/~sgtatham/putty/wishlist.html}{Wishlist |
| 66 | page} on the PuTTY website, and see if we already know about the |
| 67 | problem. If we do, it is almost certainly not necessary to mail us |
| 68 | about it, unless you think you have extra information that might be |
| 69 | helpful to us in fixing it. (Of course, if we actually \e{need} |
| 70 | specific extra information about a particular bug, the Wishlist page |
| 71 | will say so.) |
| 72 | |
| 73 | \b Check the |
| 74 | \W{http://www.chiark.greenend.org.uk/~sgtatham/putty/changes.html}{Change |
| 75 | Log} on the PuTTY website, and see if we have already fixed the bug |
| 76 | in the development snapshots. |
| 77 | |
| 78 | \b Check the |
| 79 | \W{http://www.chiark.greenend.org.uk/~sgtatham/putty/faq.html}{FAQ} |
| 80 | on the PuTTY website (also provided as \k{faq} in the manual), and |
| 81 | see if it answers your question. The FAQ lists the most common |
| 82 | things which people think are bugs, but which aren't bugs. |
| 83 | |
| 84 | \b Download the latest development snapshot and see if the problem |
| 85 | still happens with that. This really is worth doing. As a general |
| 86 | rule we aren't very interested in bugs that appear in the release |
| 87 | version but not in the development version, because that usually |
| 88 | means they are bugs we have \e{already fixed}. On the other hand, if |
| 89 | you can find a bug in the development version that doesn't appear in |
| 90 | the release, that's likely to be a new bug we've introduced since |
| 91 | the release and we're definitely interested in it. |
| 92 | |
| 93 | If none of those options solved your problem, and you still need to |
| 94 | report a bug to us, it is useful if you include some general |
| 95 | information: |
| 96 | |
| 97 | \b Tell us what version of PuTTY you are running. To find this out, |
| 98 | use the "About PuTTY" option from the System menu. Please \e{do not} |
| 99 | just tell us \q{I'm running the latest version}; e-mail can be |
| 100 | delayed and it may not be obvious which version was the latest at |
| 101 | the time you sent the message. |
| 102 | |
| 103 | \b Tell us what version of what OS you are running PuTTY on. |
| 104 | |
| 105 | \b Tell us what protocol you are connecting with: SSH, Telnet, |
| 106 | Rlogin or Raw mode. |
| 107 | |
| 108 | \b Tell us what kind of server you are connecting to; what OS, and |
| 109 | if possible what SSH server (if you're using SSH). You can get some |
| 110 | of this information from the PuTTY Event Log (see \k{using-eventlog} |
| 111 | in the manual). |
| 112 | |
| 113 | \b Send us the contents of the PuTTY Event Log, unless you |
| 114 | have a specific reason not to (for example, if it contains |
| 115 | confidential information that you think we should be able to solve |
| 116 | your problem without needing to know). |
| 117 | |
| 118 | \b Try to give us as much information as you can to help us |
| 119 | see the problem for ourselves. If possible, give us a step-by-step |
| 120 | sequence of \e{precise} instructions for reproducing the fault. |
| 121 | |
| 122 | \b Don't just tell us that PuTTY \q{does the wrong thing}; tell us |
| 123 | exactly and precisely what it did, and also tell us exactly and |
| 124 | precisely what you think it should have done instead. Some people |
| 125 | tell us PuTTY does the wrong thing, and it turns out that it was |
| 126 | doing the right thing and their expectations were wrong. Help to |
| 127 | avoid this problem by telling us exactly what you think it should |
| 128 | have done, and exactly what it did do. |
| 129 | |
| 130 | \b If you think you can, you're welcome to try to fix the problem |
| 131 | yourself. A patch to the code which fixes a bug is an excellent |
| 132 | addition to a bug report. However, a patch is never a \e{substitute} |
| 133 | for a good bug report; if your patch is wrong or inappropriate, and |
| 134 | you haven't supplied us with full information about the actual bug, |
| 135 | then we won't be able to find a better solution. |
| 136 | |
| 137 | \b |
| 138 | \W{http://www.chiark.greenend.org.uk/~sgtatham/bugs.html}\cw{http://www.chiark.greenend.org.uk/~sgtatham/bugs.html} |
| 139 | is an article on how to report bugs effectively in general. If your |
| 140 | bug report is \e{particularly} unclear, we may ask you to go away, |
| 141 | read this article, and then report the bug again. |
| 142 | |
| 143 | \H{feedback-features} Requesting extra features |
| 144 | |
| 145 | If you want to request a new feature in PuTTY, the very first things |
| 146 | you should do are: |
| 147 | |
| 148 | \b Check the |
| 149 | \W{http://www.chiark.greenend.org.uk/~sgtatham/putty/wishlist.html}{Wishlist |
| 150 | page} on the PuTTY website, and see if your feature is already on |
| 151 | the list. If it is, it probably won't achieve very much to repeat |
| 152 | the request. (But see \k{feedback-feature-priority} if you want to |
| 153 | persuade us to give your particular feature higher priority.) |
| 154 | |
| 155 | \b Check the |
| 156 | \W{http://www.chiark.greenend.org.uk/~sgtatham/putty/changes.html}{Change |
| 157 | Log} on the PuTTY website, and see if we have already added your |
| 158 | feature in the development snapshots. If it isn't clear, download |
| 159 | the latest development snapshot and see if the feature is present. |
| 160 | If it is, then it will also be in the next release and there is no |
| 161 | need to mail us at all. |
| 162 | |
| 163 | If you can't find your feature in either the development snapshots |
| 164 | \e{or} the Wishlist, then you probably do need to submit a feature |
| 165 | request. Since the PuTTY authors are very busy, it helps if you try |
| 166 | to do some of the work for us: |
| 167 | |
| 168 | \b Do as much of the design as you can. Think about \q{corner |
| 169 | cases}; think about how your feature interacts with other existing |
| 170 | features. Think about the user interface; if you can't come up with |
| 171 | a simple and intuitive interface to your feature, you shouldn't be |
| 172 | surprised if we can't either. Always imagine whether it's possible |
| 173 | for there to be more than one, or less than one, of something you'd |
| 174 | assumed there would be one of. (For example, if you were to want |
| 175 | PuTTY to put an icon in the System tray rather than the Taskbar, you |
| 176 | should think about what happens if there's more than one PuTTY |
| 177 | active; how would the user tell which was which?) |
| 178 | |
| 179 | \b If you can program, it may be worth offering to write the feature |
| 180 | yourself and send us a patch. However, it is likely to be helpful |
| 181 | if you confer with us first; there may be design issues you haven't |
| 182 | thought of, or we may be about to make big changes to the code which |
| 183 | your patch would clash with, or something. If you check with the |
| 184 | maintainers first, there is a better chance of your code actually |
| 185 | being usable. |
| 186 | |
| 187 | \H{feedback-feature-priority} Requesting features that have already |
| 188 | been requested |
| 189 | |
| 190 | If a feature is already listed on the Wishlist, then it usually |
| 191 | means we would like to add it to PuTTY at some point. However, this |
| 192 | may not be in the near future. If there's a feature on the Wishlist |
| 193 | which you would like to see in the \e{near} future, there are |
| 194 | several things you can do to try to increase its priority level: |
| 195 | |
| 196 | \b Mail us and vote for it. (Be sure to mention that you've seen it |
| 197 | on the Wishlist, or we might think you haven't even \e{read} the |
| 198 | Wishlist). This probably won't have very \e{much} effect; if a huge |
| 199 | number of people vote for something then it may make a difference, |
| 200 | but one or two extra votes for a particular feature are unlikely to |
| 201 | change our priority list immediately. Also, don't expect a reply. |
| 202 | |
| 203 | \b Offer us money if we do the work sooner rather than later. This |
| 204 | sometimes works, but not always. The PuTTY team all have full-time |
| 205 | jobs and we're doing all of this work in our free time; we may |
| 206 | sometimes be willing to give up some more of our free time in |
| 207 | exchange for some money, but if you try to bribe us for a \e{big} |
| 208 | feature it's entirely possible that we simply won't have the time to |
| 209 | spare - whether you pay us or not. (Also, we don't accept bribes to |
| 210 | add \e{bad} features to the Wishlist, because our desire to provide |
| 211 | high-quality software to the users comes first.) |
| 212 | |
| 213 | \b Offer to help us write the code. This is probably the \e{only} |
| 214 | way to get a feature implemented quickly, if it's a big one that we |
| 215 | don't have time to do ourselves. |
| 216 | |
| 217 | \H{feedback-webadmin} Web server administration |
| 218 | |
| 219 | If the PuTTY web site is down (Connection Timed Out), please don't |
| 220 | bother mailing us to tell us about it. Most of us read our e-mail on |
| 221 | the same machines that host the web site, so if those machines are |
| 222 | down then we will notice \e{before} we read our e-mail. So there's |
| 223 | no point telling us our servers are down. |
| 224 | |
| 225 | Of course, if the web site has some other error (Connection Refused, |
| 226 | 404 Not Found, 403 Forbidden, or something else) then we might |
| 227 | \e{not} have noticed and it might still be worth telling us about it. |
| 228 | |
| 229 | \H{feedback-permission} Asking permission for things |
| 230 | |
| 231 | PuTTY is distributed under the MIT Licence (see \k{licence} for |
| 232 | details). This means you can do almost \e{anything} you like with |
| 233 | our software, our source code, and our documentation. The only |
| 234 | things you aren't allowed to do are to remove our copyright notices |
| 235 | or the licence text itself, or to hold us legally responsible if |
| 236 | something goes wrong. |
| 237 | |
| 238 | So if you want permission to include PuTTY on a magazine cover disk, |
| 239 | or as part of a collection of useful software on a CD or a web site, |
| 240 | then \e{permission is already granted}. You don't have to mail us |
| 241 | and ask. Just go ahead and do it. We don't mind. |
| 242 | |
| 243 | If you want to use parts of the PuTTY source code in another |
| 244 | program, then it might be worth mailing us to talk about technical |
| 245 | details, but if all you want is to ask permission then you don't |
| 246 | need to bother. You already have permission. |
| 247 | |
| 248 | \H{feedback-mirrors} Mirroring the PuTTY web site |
| 249 | |
| 250 | All mirrors of the PuTTY web site are welcome. Please don't bother |
| 251 | asking us for permission before setting up a mirror. You already |
| 252 | have permission. We are always happy to have more mirrors. |
| 253 | |
| 254 | If you mail us \e{after} you have set up the mirror, and remember to |
| 255 | let us know which country your mirror is in, then we'll add it to |
| 256 | the |
| 257 | \W{http://www.chiark.greenend.org.uk/~sgtatham/putty/mirrors.html}{Mirrors |
| 258 | page} on the PuTTY website. |
| 259 | |
| 260 | If you have technical questions about the process of mirroring, then |
| 261 | you might want to mail us before setting up the mirror; but if you |
| 262 | just want to ask for permission, you don't need to. You already have |
| 263 | permission. |
| 264 | |
| 265 | \H{feedback-compliments} Praise and compliments |
| 266 | |
| 267 | One of the most rewarding things about maintaining free software is |
| 268 | getting e-mails that just say \q{thanks}. We are always happy to |
| 269 | receive e-mails of this type. |
| 270 | |
| 271 | Regrettably we don't have time to answer them all in person. If you |
| 272 | mail us a compliment and don't receive a reply, \e{please} don't |
| 273 | think we've ignored you. We did receive it and we were happy about |
| 274 | it; we just didn't have time to tell you so personally. |
| 275 | |
| 276 | To everyone who's ever sent us praise and compliments, in the past |
| 277 | and the future: \e{you're welcome}! |
| 278 | |
| 279 | \H{feedback-address} E-mail address |
| 280 | |
| 281 | The actual address to mail is |
| 282 | \cw{<\W{mailto:putty@projects.tartarus.org}{putty@projects.tartarus.org}>}. |