]>
Commit | Line | Data |
---|---|---|
86d33001 DS |
1 | <!-- |
2 | Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. | |
3 | ||
4 | SPDX-License-Identifier: curl | |
5 | --> | |
6 | ||
6f82ebd8 DS |
7 | # BUGS |
8 | ||
9 | ## There are still bugs | |
10 | ||
11 | Curl and libcurl keep being developed. Adding features and changing code | |
2097a095 | 12 | means that bugs sneak in, no matter how hard we try to keep them out. |
6f82ebd8 | 13 | |
e5000e79 | 14 | Of course there are lots of bugs left. Not to mention misfeatures. |
6f82ebd8 DS |
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 | ||
a28464ae | 21 | If you cannot fix a bug yourself and submit a fix for it, try to report an as |
6f82ebd8 DS |
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 | ||
76d6e719 | 26 | Please read the rest of this document below first before doing that. |
6f82ebd8 DS |
27 | |
28 | If you feel you need to ask around first, find a suitable [mailing list]( | |
4d2f8006 | 29 | https://curl.se/mail/) and post your questions there. |
6f82ebd8 DS |
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 | |
2097a095 DS |
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. | |
6f82ebd8 DS |
46 | |
47 | The curl project's process for handling security related issues is | |
4d2f8006 | 48 | [documented separately](https://curl.se/dev/secprocess.html). |
6f82ebd8 DS |
49 | |
50 | ## What to report | |
51 | ||
2097a095 | 52 | When reporting a bug, you should include all information to help us |
e28edb66 | 53 | understand what is wrong, what you expected to happen and how to repeat the |
6f82ebd8 DS |
54 | bad behavior. You therefore need to tell us: |
55 | ||
56 | - your operating system's name and version number | |
57 | ||
a28464ae | 58 | - what version of curl you are using (`curl -V` is fine) |
6f82ebd8 DS |
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 use 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 | |
2097a095 DS |
67 | pieces in your report. You benefit from this yourself, as it enables us to |
68 | help you quicker and more accurately. | |
6f82ebd8 DS |
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 | ||
94ac2ca7 | 74 | If curl crashed, causing a core dump (in Unix), there is hardly any use to |
76d6e719 DS |
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. | |
6f82ebd8 DS |
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 | ||
a28464ae | 84 | When you have written your own application with libcurl to perform transfers, |
6f82ebd8 DS |
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 | |
a28464ae | 89 | you are using and what name resolving your libcurl uses. If you use SFTP or |
6f82ebd8 DS |
90 | SCP, the libssh2 version is relevant etc. |
91 | ||
92 | Showing us a real source code example repeating your problem is the best way | |
2097a095 DS |
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). | |
6f82ebd8 DS |
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 | ||
2097a095 | 101 | ## Who fixes the problems |
6f82ebd8 DS |
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 | ||
2097a095 DS |
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. | |
6f82ebd8 DS |
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 | |
a28464ae | 123 | do not 'strip' the final executable. Try to avoid optimizing the code as well, |
6f82ebd8 DS |
124 | remove `-O`, `-O2` etc from the compiler options. |
125 | ||
126 | Run the program until it cores. | |
127 | ||
2097a095 DS |
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. | |
6f82ebd8 DS |
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 | |
2097a095 | 137 | crashed. Include the stack trace with your detailed bug report, it helps a |
6f82ebd8 DS |
138 | lot. |
139 | ||
140 | ## Bugs in libcurl bindings | |
141 | ||
2097a095 DS |
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. | |
6f82ebd8 DS |
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 | |
4d2f8006 | 153 | bug fixes and more, see: https://curl.se/docs/releases.html |
6f82ebd8 DS |
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 | |
a28464ae | 157 | old versions when chances are we already fixed them or at least that they have |
6f82ebd8 DS |
158 | changed nature and appearance in later versions. |
159 | ||
160 | When you experience a problem and want to report it, you really SHOULD | |
a28464ae DS |
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, | |
6f82ebd8 DS |
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 | |
75670e45 | 171 | instead, they "just want the bug fixed". That is fine, just do not count on us |
a28464ae DS |
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 | |
6f82ebd8 DS |
174 | experiencing. |
175 | ||
176 | Security wise, it is almost always a bad idea to lag behind the current curl | |
8749ce65 | 177 | versions by a lot. We keep discovering and reporting security problems |
6f82ebd8 | 178 | over time see you can see in [this |
4d2f8006 | 179 | table](https://curl.se/docs/vulnerabilities.html) |
6f82ebd8 DS |
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 | |
b341b767 | 186 | team of developers first needs to see the report. Maybe they took the day off, |
a28464ae | 187 | maybe they are off in the woods hunting. Have patience. Allow at least a few |
6f82ebd8 DS |
188 | days before expecting someone to have responded. |
189 | ||
2097a095 DS |
190 | In the issue tracker, you can expect that some labels are set on the issue to |
191 | help categorize it. | |
6f82ebd8 DS |
192 | |
193 | ## First response | |
194 | ||
a28464ae | 195 | If your issue/bug report was not perfect at once (and few are), chances are |
2097a095 | 196 | that someone asks follow-up questions. Which version did you use? Which |
6f82ebd8 DS |
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 | ||
ce3dce90 | 208 | We may require further work from you who actually see or experience the |
e28edb66 | 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. | |
6f82ebd8 DS |
211 | |
212 | ## Unresponsive | |
213 | ||
e28edb66 | 214 | If the problem have not been understood or reproduced, and there is nobody |
6f82ebd8 DS |
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 | |
76d6e719 | 217 | strong suggestion that the bug is unimportant. |
6f82ebd8 | 218 | |
2097a095 DS |
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 | |
6f82ebd8 DS |
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 | |
a28464ae | 227 | perfectly valid problems that *should* get fixed but apparently are not. We |
6f82ebd8 | 228 | try to mark such bugs as `KNOWN_BUGS material` after a time of inactivity and |
e7227023 DS |
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. | |
6f82ebd8 DS |
231 | |
232 | ## `KNOWN_BUGS` | |
233 | ||
234 | This is a list of known bugs. Bugs we know exist and that have been pointed | |
a28464ae | 235 | out but that have not yet been fixed. The reasons for why they have not been |
6f82ebd8 DS |
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 | ||
e7227023 DS |
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. | |
6f82ebd8 DS |
242 | |
243 | The `KNOWN_BUGS` document has a sibling document known as `TODO`. | |
244 | ||
245 | ## `TODO` | |
246 | ||
a28464ae | 247 | Issues that are filed or reported that are not really bugs but more missing |
6f82ebd8 | 248 | features or ideas for future improvements and so on are marked as |
2097a095 DS |
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. | |
6f82ebd8 DS |
251 | |
252 | The `TODO` document is full of ideas and suggestions of what we can add or | |
ff021cb2 | 253 | fix one day. You are always encouraged and free to grab one of those items and |
6f82ebd8 DS |
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 | ||
e7227023 DS |
258 | If an issue is rather a bug and not a missing feature or functionality, it is |
259 | listed in `KNOWN_BUGS` instead. | |
6f82ebd8 DS |
260 | |
261 | ## Closing off stalled bugs | |
262 | ||
2097a095 DS |
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. | |
6f82ebd8 | 268 | |
e7227023 | 269 | This way, we only have "active" issues open on GitHub. Irrelevant issues and |
2097a095 | 270 | pull requests do not distract developers or casual visitors. |