docs/BUGS

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