BUGS.md (11941B)
1 <!-- 2 Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. 3 4 SPDX-License-Identifier: curl 5 --> 6 7 # BUGS 8 9 ## There are still bugs 10 11 curl and libcurl keep being developed. Adding features and changing code 12 means that bugs sneak in, no matter how hard we try to keep them out. 13 14 Of course there are lots of bugs left. Not to mention misfeatures. 15 16 To help us make curl the stable and solid product we want it to be, we need 17 bug reports and bug fixes. 18 19 ## Where to report 20 21 If you cannot fix a bug yourself and submit a fix for it, try to report an as 22 detailed report as possible to a curl mailing list to allow one of us to have 23 a go at a solution. You can optionally also submit your problem in [curl's 24 bug tracking system](https://github.com/curl/curl/issues). 25 26 Please read the rest of this document below first before doing that. 27 28 If you feel you need to ask around first, find a suitable [mailing 29 list](https://curl.se/mail/) and post your questions there. 30 31 ## Security bugs 32 33 If you find a bug or problem in curl or libcurl that you think has a security 34 impact, for example a bug that can put users in danger or make them 35 vulnerable if the bug becomes public knowledge, then please report that bug 36 using our security development process. 37 38 Security related bugs or bugs that are suspected to have a security impact, 39 should be reported on the [curl security tracker at 40 HackerOne](https://hackerone.com/curl). 41 42 This ensures that the report reaches the curl security team so that they 43 first can deal with the report away from the public to minimize the harm and 44 impact it has on existing users out there who might be using the vulnerable 45 versions. 46 47 The curl project's process for handling security related issues is 48 [documented separately](https://curl.se/dev/secprocess.html). 49 50 ## What to report 51 52 When reporting a bug, you should include all information to help us 53 understand what is wrong, what you expected to happen and how to repeat the 54 bad behavior. You therefore need to tell us: 55 56 - your operating system's name and version number 57 58 - what version of curl you are using (`curl -V` is fine) 59 60 - versions of the used libraries that libcurl is built to use 61 62 - what URL you were working with (if possible), at least which protocol 63 64 and anything and everything else you think matters. Tell us what you expected 65 to happen, tell us what did happen, tell us how you could make it work 66 another way. Dig around, try out, test. Then include all the tiny bits and 67 pieces in your report. You benefit from this yourself, as it enables us to 68 help you quicker and more accurately. 69 70 Since curl deals with networks, it often helps us if you include a protocol 71 debug dump with your bug report. The output you get by using the `-v` or 72 `--trace` options. 73 74 If curl crashed, causing a core dump (in Unix), there is hardly any use to 75 send that huge file to anyone of us. Unless we have the same system setup as 76 you, we cannot do much with it. Instead, we ask you to get a stack trace and 77 send that (much smaller) output to us instead. 78 79 The address and how to subscribe to the mailing lists are detailed in the 80 `MANUAL.md` file. 81 82 ## libcurl problems 83 84 When you have written your own application with libcurl to perform transfers, 85 it is even more important to be specific and detailed when reporting bugs. 86 87 Tell us the libcurl version and your operating system. Tell us the name and 88 version of all relevant sub-components like for example the SSL library 89 you are using and what name resolving your libcurl uses. If you use SFTP or 90 SCP, the libssh2 version is relevant etc. 91 92 Showing us a real source code example repeating your problem is the best way 93 to get our attention and it greatly increases our chances to understand your 94 problem and to work on a fix (if we agree it truly is a problem). 95 96 Lots of problems that appear to be libcurl problems are actually just abuses 97 of the libcurl API or other malfunctions in your applications. It is advised 98 that you run your problematic program using a memory debug tool like valgrind 99 or similar before you post memory-related or "crashing" problems to us. 100 101 ## Who fixes the problems 102 103 If the problems or bugs you describe are considered to be bugs, we want to 104 have the problems fixed. 105 106 There are no developers in the curl project that are paid to work on bugs. 107 All developers that take on reported bugs do this on a voluntary basis. We do 108 it out of an ambition to keep curl and libcurl excellent products and out of 109 pride. 110 111 Please do not assume that you can just lump over something to us and it then 112 magically gets fixed after some given time. Most often we need feedback and 113 help to understand what you have experienced and how to repeat a problem. 114 Then we may only be able to assist YOU to debug the problem and to track down 115 the proper fix. 116 117 We get reports from many people every month and each report can take a 118 considerable amount of time to really go to the bottom with. 119 120 ## How to get a stack trace 121 122 First, you must make sure that you compile all sources with `-g` and that you 123 do not 'strip' the final executable. Try to avoid optimizing the code as well, 124 remove `-O`, `-O2` etc from the compiler options. 125 126 Run the program until it cores. 127 128 Run your debugger on the core file, like `<debugger> curl core`. `<debugger>` 129 should be replaced with the name of your debugger, in most cases that is 130 `gdb`, but `dbx` and others also occur. 131 132 When the debugger has finished loading the core file and presents you a 133 prompt, enter `where` (without quotes) and press return. 134 135 The list that is presented is the stack trace. If everything worked, it is 136 supposed to contain the chain of functions that were called when curl 137 crashed. Include the stack trace with your detailed bug report, it helps a 138 lot. 139 140 ## Bugs in libcurl bindings 141 142 There are of course bugs in libcurl bindings. You should then primarily 143 approach the team that works on that particular binding and see what you can 144 do to help them fix the problem. 145 146 If you suspect that the problem exists in the underlying libcurl, then please 147 convert your program over to plain C and follow the steps outlined above. 148 149 ## Bugs in old versions 150 151 The curl project typically releases new versions every other month, and we 152 fix several hundred bugs per year. For a huge table of releases, number of 153 bug fixes and more, see: https://curl.se/docs/releases.html 154 155 The developers in the curl project do not have bandwidth or energy enough to 156 maintain several branches or to spend much time on hunting down problems in 157 old versions when chances are we already fixed them or at least that they have 158 changed nature and appearance in later versions. 159 160 When you experience a problem and want to report it, you really SHOULD 161 include the version number of the curl you are using when you experience the 162 issue. If that version number shows us that you are using an out-of-date curl, 163 you should also try out a modern curl version to see if the problem persists 164 or how/if it has changed in appearance. 165 166 Even if you cannot immediately upgrade your application/system to run the 167 latest curl version, you can most often at least run a test version or 168 experimental build or similar, to get this confirmed or not. 169 170 At times people insist that they cannot upgrade to a modern curl version, but 171 instead, they "just want the bug fixed". That is fine, just do not count on us 172 spending many cycles on trying to identify which single commit, if that is 173 even possible, that at some point in the past fixed the problem you are now 174 experiencing. 175 176 Security wise, it is almost always a bad idea to lag behind the current curl 177 versions by a lot. We keep discovering and reporting security problems 178 over time see you can see in [this 179 table](https://curl.se/docs/vulnerabilities.html) 180 181 # Bug fixing procedure 182 183 ## What happens on first filing 184 185 When a new issue is posted in the issue tracker or on the mailing list, the 186 team of developers first needs to see the report. Maybe they took the day off, 187 maybe they are off in the woods hunting. Have patience. Allow at least a few 188 days before expecting someone to have responded. 189 190 In the issue tracker, you can expect that some labels are set on the issue to 191 help categorize it. 192 193 ## First response 194 195 If your issue/bug report was not perfect at once (and few are), chances are 196 that someone asks follow-up questions. Which version did you use? Which 197 options did you use? How often does the problem occur? How can we reproduce 198 this problem? Which protocols does it involve? Or perhaps much more specific 199 and deep diving questions. It all depends on your specific issue. 200 201 You should then respond to these follow-up questions and provide more info 202 about the problem, so that we can help you figure it out. Or maybe you can 203 help us figure it out. An active back-and-forth communication is important 204 and the key for finding a cure and landing a fix. 205 206 ## Not reproducible 207 208 We may require further work from you who actually see or experience the 209 problem if we cannot reproduce it and cannot understand it even after having 210 gotten all the info we need and having studied the source code over again. 211 212 ## Unresponsive 213 214 If the problem have not been understood or reproduced, and there is nobody 215 responding to follow-up questions or questions asking for clarifications or 216 for discussing possible ways to move forward with the task, we take that as a 217 strong suggestion that the bug is unimportant. 218 219 Unimportant issues are closed as inactive sooner or later as they cannot be 220 fixed. The inactivity period (waiting for responses) should not be shorter 221 than two weeks but may extend months. 222 223 ## Lack of time/interest 224 225 Bugs that are filed and are understood can unfortunately end up in the 226 "nobody cares enough about it to work on it" category. Such bugs are 227 perfectly valid problems that *should* get fixed but apparently are not. We 228 try to mark such bugs as `KNOWN_BUGS material` after a time of inactivity and 229 if no activity is noticed after yet some time those bugs are added to the 230 `KNOWN_BUGS` document and are closed in the issue tracker. 231 232 ## `KNOWN_BUGS` 233 234 This is a list of known bugs. Bugs we know exist and that have been pointed 235 out but that have not yet been fixed. The reasons for why they have not been 236 fixed can involve anything really, but the primary reason is that nobody has 237 considered these problems to be important enough to spend the necessary time 238 and effort to have them fixed. 239 240 The `KNOWN_BUGS` items are always up for grabs and we love the ones who bring 241 one of them back to life and offer solutions to them. 242 243 The `KNOWN_BUGS` document has a sibling document known as `TODO`. 244 245 ## `TODO` 246 247 Issues that are filed or reported that are not really bugs but more missing 248 features or ideas for future improvements and so on are marked as 249 *enhancement* or *feature-request* and get added to the `TODO` document and 250 the issues are closed. We do not keep TODO items open in the issue tracker. 251 252 The `TODO` document is full of ideas and suggestions of what we can add or 253 fix one day. You are always encouraged and free to grab one of those items and 254 take up a discussion with the curl development team on how that could be 255 implemented or provided in the project so that you can work on ticking it odd 256 that document. 257 258 If an issue is rather a bug and not a missing feature or functionality, it is 259 listed in `KNOWN_BUGS` instead. 260 261 ## Closing off stalled bugs 262 263 The [issue and pull request trackers](https://github.com/curl/curl) only hold 264 "active" entries open (using a non-precise definition of what active actually 265 is, but they are at least not completely dead). Those that are abandoned or 266 in other ways dormant are closed and sometimes added to `TODO` and 267 `KNOWN_BUGS` instead. 268 269 This way, we only have "active" issues open on GitHub. Irrelevant issues and 270 pull requests do not distract developers or casual visitors.