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