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