From 6f82ebd8ae7c7ae529a91931d2537d35375124f1 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Fri, 18 Sep 2020 13:44:57 +0200 Subject: BUGS: convert document to markdown Closes #5979 --- docs/BUGS | 302 ------------------------------------------------------- docs/BUGS.md | 266 ++++++++++++++++++++++++++++++++++++++++++++++++ docs/Makefile.am | 2 +- 3 files changed, 267 insertions(+), 303 deletions(-) delete mode 100644 docs/BUGS create mode 100644 docs/BUGS.md (limited to 'docs') diff --git a/docs/BUGS b/docs/BUGS deleted file mode 100644 index 480e0caec..000000000 --- a/docs/BUGS +++ /dev/null @@ -1,302 +0,0 @@ - _ _ ____ _ - ___| | | | _ \| | - / __| | | | |_) | | - | (__| |_| | _ <| |___ - \___|\___/|_| \_\_____| - -BUGS - - 1. Bugs - 1.1 There are still bugs - 1.2 Where to report - 1.3 Security bugs - 1.4 What to report - 1.5 libcurl problems - 1.6 Who will fix the problems - 1.7 How to get a stack trace - 1.8 Bugs in libcurl bindings - 1.9 Bugs in old versions - - 2. Bug fixing procedure - 2.1 What happens on first filing - 2.2 First response - 2.3 Not reproducible - 2.4 Unresponsive - 2.5 Lack of time/interest - 2.6 KNOWN_BUGS - 2.7 TODO - 2.8 Closing off stalled bugs - -============================================================================== - -1.1 There are still bugs - - Curl and libcurl keep being developed. Adding features and changing code - means that bugs will sneak in, no matter how hard we try not to. - - Of course there are lots of bugs left. And lots of misfeatures. - - To help us make curl the stable and solid product we want it to be, we need - bug reports and bug fixes. - -1.2 Where to report - - If you can't fix a bug yourself and submit a fix for it, try to report an as - detailed report as possible to a curl mailing list to allow one of us to - have a go at a solution. You can optionally also post your bug/problem at - curl's bug tracking system over at - - https://github.com/curl/curl/issues - - Please read the rest of this document below first before doing that! - - If you feel you need to ask around first, find a suitable mailing list and - post there. The lists are available on https://curl.haxx.se/mail/ - -1.3 Security bugs - - If you find a bug or problem in curl or libcurl that you think has a - security impact, for example a bug that can put users in danger or make them - vulnerable if the bug becomes public knowledge, then please report that bug - using our security development process. - - Security related bugs or bugs that are suspected to have a security impact, - should be reported on the curl security tracker at HackerOne: - - https://hackerone.com/curl - - This ensures that the report reaches the curl security team so that they - first can be deal with the report away from the public to minimize the harm - and impact it will have on existing users out there who might be using the - vulnerable versions. - - The curl project's process for handling security related issues is - documented here: - - https://curl.haxx.se/dev/secprocess.html - -1.4 What to report - - When reporting a bug, you should include all information that will help us - understand what's wrong, what you expected to happen and how to repeat the - bad behavior. You therefore need to tell us: - - - your operating system's name and version number - - - what version of curl you're using (curl -V is fine) - - - versions of the used libraries that libcurl is built to use - - - what URL you were working with (if possible), at least which protocol - - and anything and everything else you think matters. Tell us what you - expected to happen, tell use what did happen, tell us how you could make it - work another way. Dig around, try out, test. Then include all the tiny bits - and pieces in your report. You will benefit from this yourself, as it will - enable us to help you quicker and more accurately. - - Since curl deals with networks, it often helps us if you include a protocol - debug dump with your bug report. The output you get by using the -v or - --trace options. - - If curl crashed, causing a core dump (in unix), there is hardly any use to - send that huge file to anyone of us. Unless we have an exact same system - setup as you, we can't do much with it. Instead we ask you to get a stack - trace and send that (much smaller) output to us instead! - - The address and how to subscribe to the mailing lists are detailed in the - MANUAL file. - -1.5 libcurl problems - - When you've written your own application with libcurl to perform transfers, - it is even more important to be specific and detailed when reporting bugs. - - Tell us the libcurl version and your operating system. Tell us the name and - version of all relevant sub-components like for example the SSL library - you're using and what name resolving your libcurl uses. If you use SFTP or - SCP, the libssh2 version is relevant etc. - - Showing us a real source code example repeating your problem is the best way - to get our attention and it will greatly increase our chances to understand - your problem and to work on a fix (if we agree it truly is a problem). - - Lots of problems that appear to be libcurl problems are actually just abuses - of the libcurl API or other malfunctions in your applications. It is advised - that you run your problematic program using a memory debug tool like - valgrind or similar before you post memory-related or "crashing" problems to - us. - -1.6 Who will fix the problems - - If the problems or bugs you describe are considered to be bugs, we want to - have the problems fixed. - - There are no developers in the curl project that are paid to work on bugs. - All developers that take on reported bugs do this on a voluntary basis. We - do it out of an ambition to keep curl and libcurl excellent products and out - of pride. - - But please do not assume that you can just lump over something to us and it - will then magically be fixed after some given time. Most often we need - feedback and help to understand what you've experienced and how to repeat a - problem. Then we may only be able to assist YOU to debug the problem and to - track down the proper fix. - - We get reports from many people every month and each report can take a - considerable amount of time to really go to the bottom with. - -1.7 How to get a stack trace - - First, you must make sure that you compile all sources with -g and that you - don't 'strip' the final executable. Try to avoid optimizing the code as - well, remove -O, -O2 etc from the compiler options. - - Run the program until it cores. - - Run your debugger on the core file, like ' curl core'. - should be replaced with the name of your debugger, in most cases that will - be 'gdb', but 'dbx' and others also occur. - - When the debugger has finished loading the core file and presents you a - prompt, enter 'where' (without the quotes) and press return. - - The list that is presented is the stack trace. If everything worked, it is - supposed to contain the chain of functions that were called when curl - crashed. Include the stack trace with your detailed bug report. It'll help a - lot. - -1.8 Bugs in libcurl bindings - - There will of course pop up bugs in libcurl bindings. You should then - primarily approach the team that works on that particular binding and see - what you can do to help them fix the problem. - - If you suspect that the problem exists in the underlying libcurl, then - please convert your program over to plain C and follow the steps outlined - above. - -1.9 Bugs in old versions - - The curl project typically releases new versions every other month, and we - fix several hundred bugs per year. For a huge table of releases, number of - bug fixes and more, see: https://curl.haxx.se/docs/releases.html - - The developers in the curl project do not have bandwidth or energy enough to - maintain several branches or to spend much time on hunting down problems in - old versions when chances are we already fixed them or at least that they've - changed nature and appearance in later versions. - - When you experience a problem and want to report it, you really SHOULD - include the version number of the curl you're using when you experience the - issue. If that version number shows us that you're using an out-of-date - curl, you should also try out a modern curl version to see if the problem - persists or how/if it has changed in appearance. - - Even if you cannot immediately upgrade your application/system to run the - latest curl version, you can most often at least run a test version or - experimental build or similar, to get this confirmed or not. - - At times people insist that they cannot upgrade to a modern curl version, - but instead they "just want the bug fixed". That's fine, just don't count on - us spending many cycles on trying to identify which single commit, if that's - even possible, that at some point in the past fixed the problem you're now - experiencing. - - Security wise, it is almost always a bad idea to lag behind the current curl - versions by a lot. We keeping discovering and reporting security problems - over time see you can see in this table: - https://curl.haxx.se/docs/vulnerabilities.html - -2. Bug fixing procedure - -2.1 What happens on first filing - - When a new issue is posted in the issue tracker or on the mailing list, the - team of developers first need to see the report. Maybe they took the day - off, maybe they're off in the woods hunting. Have patience. Allow at least a - few days before expecting someone to have responded. - - In the issue tracker you can expect that some labels will be set on the - issue to help categorize it. - -2.2 First response - - If your issue/bug report wasn't perfect at once (and few are), chances are - that someone will ask follow-up questions. Which version did you use? Which - options did you use? How often does the problem occur? How can we reproduce - this problem? Which protocols does it involve? Or perhaps much more specific - and deep diving questions. It all depends on your specific issue. - - You should then respond to these follow-up questions and provide more info - about the problem, so that we can help you figure it out. Or maybe you can - help us figure it out. An active back-and-forth communication is important - and the key for finding a cure and landing a fix. - -2.3 Not reproducible - - For problems that we can't reproduce and can't understand even after having - gotten all the info we need and having studied the source code over again, - are really hard to solve so then we may require further work from you who - actually see or experience the problem. - -2.4 Unresponsive - - If the problem haven't been understood or reproduced, and there's nobody - responding to follow-up questions or questions asking for clarifications or - for discussing possible ways to move forward with the task, we take that as - a strong suggestion that the bug is not important. - - Unimportant issues will be closed as inactive sooner or later as they can't - be fixed. The inactivity period (waiting for responses) should not be - shorter than two weeks but may extend months. - -2.5 Lack of time/interest - - Bugs that are filed and are understood can unfortunately end up in the - "nobody cares enough about it to work on it" category. Such bugs are - perfectly valid problems that *should* get fixed but apparently aren't. We - try to mark such bugs as "KNOWN_BUGS material" after a time of inactivity - and if no activity is noticed after yet some time those bugs are added to - KNOWN_BUGS and are closed in the issue tracker. - -2.6 KNOWN_BUGS - - This is a list of known bugs. Bugs we know exist and that have been pointed - out but that haven't yet been fixed. The reasons for why they haven't been - fixed can involve anything really, but the primary reason is that nobody has - considered these problems to be important enough to spend the necessary time - and effort to have them fixed. - - The KNOWN_BUGS are always up for grabs and we will always love the ones who - bring one of them back to live and offers solutions to them. - - The KNOWN_BUGS document has a sibling document known as TODO. - -2.7 TODO - - Issues that are filed or reported that aren't really bugs but more missing - features or ideas for future improvements and so on are marked as - 'enhancement' or 'feature-request' and will be added to the TODO document - instead and the issue is closed. We don't keep TODO items in the issue - tracker. - - The TODO document is full of ideas and suggestions of what we can add or fix - one day. You're always encouraged and free to grab one of those items and - take up a discussion with the curl development team on how that could be - implemented or provided in the project so that you can work on ticking it - odd that document. - - If the issue is rather a bug and not a missing feature or functionality, it - is listed in KNOWN_BUGS instead. - -2.8 Closing off stalled bugs - - The issue and pull request trackers on https://github.com/curl/curl will - only hold "active" entries (using a non-precise definition of what active - actually is, but they're at least not completely dead). Those that are - abandoned or in other ways dormant will be closed and sometimes added to - TODO and KNOWN_BUGS instead. - - This way, we only have "active" issues open on github. Irrelevant issues and - pull requests will not distract developers or casual visitors. diff --git a/docs/BUGS.md b/docs/BUGS.md new file mode 100644 index 000000000..cc09a5d1b --- /dev/null +++ b/docs/BUGS.md @@ -0,0 +1,266 @@ +# BUGS + +## There are still bugs + + Curl and libcurl keep being developed. Adding features and changing code + means that bugs will sneak in, no matter how hard we try not to. + + Of course there are lots of bugs left. And lots of misfeatures. + + To help us make curl the stable and solid product we want it to be, we need + bug reports and bug fixes. + +## Where to report + + If you can't fix a bug yourself and submit a fix for it, try to report an as + detailed report as possible to a curl mailing list to allow one of us to have + a go at a solution. You can optionally also submit your problem in [curl's + bug tracking system](https://github.com/curl/curl/issues). + + Please read the rest of this document below first before doing that! + + If you feel you need to ask around first, find a suitable [mailing list]( + https://curl.haxx.se/mail/) and post your questions there. + +## Security bugs + + If you find a bug or problem in curl or libcurl that you think has a security + impact, for example a bug that can put users in danger or make them + vulnerable if the bug becomes public knowledge, then please report that bug + using our security development process. + + Security related bugs or bugs that are suspected to have a security impact, + should be reported on the [curl security tracker at + HackerOne](https://hackerone.com/curl). + + This ensures that the report reaches the curl security team so that they + first can be deal with the report away from the public to minimize the harm + and impact it will have on existing users out there who might be using the + vulnerable versions. + + The curl project's process for handling security related issues is + [documented separately](https://curl.haxx.se/dev/secprocess.html). + +## What to report + + When reporting a bug, you should include all information that will help us + understand what's wrong, what you expected to happen and how to repeat the + bad behavior. You therefore need to tell us: + + - your operating system's name and version number + + - what version of curl you're using (`curl -V` is fine) + + - versions of the used libraries that libcurl is built to use + + - what URL you were working with (if possible), at least which protocol + + and anything and everything else you think matters. Tell us what you expected + to happen, tell use what did happen, tell us how you could make it work + another way. Dig around, try out, test. Then include all the tiny bits and + pieces in your report. You will benefit from this yourself, as it will enable + us to help you quicker and more accurately. + + Since curl deals with networks, it often helps us if you include a protocol + debug dump with your bug report. The output you get by using the `-v` or + `--trace` options. + + If curl crashed, causing a core dump (in unix), there is hardly any use to + send that huge file to anyone of us. Unless we have an exact same system + setup as you, we can't do much with it. Instead we ask you to get a stack + trace and send that (much smaller) output to us instead! + + The address and how to subscribe to the mailing lists are detailed in the + `MANUAL.md` file. + +## libcurl problems + + When you've written your own application with libcurl to perform transfers, + it is even more important to be specific and detailed when reporting bugs. + + Tell us the libcurl version and your operating system. Tell us the name and + version of all relevant sub-components like for example the SSL library + you're using and what name resolving your libcurl uses. If you use SFTP or + SCP, the libssh2 version is relevant etc. + + Showing us a real source code example repeating your problem is the best way + to get our attention and it will greatly increase our chances to understand + your problem and to work on a fix (if we agree it truly is a problem). + + Lots of problems that appear to be libcurl problems are actually just abuses + of the libcurl API or other malfunctions in your applications. It is advised + that you run your problematic program using a memory debug tool like valgrind + or similar before you post memory-related or "crashing" problems to us. + +## Who will fix the problems + + If the problems or bugs you describe are considered to be bugs, we want to + have the problems fixed. + + There are no developers in the curl project that are paid to work on bugs. + All developers that take on reported bugs do this on a voluntary basis. We do + it out of an ambition to keep curl and libcurl excellent products and out of + pride. + + But please do not assume that you can just lump over something to us and it + will then magically be fixed after some given time. Most often we need + feedback and help to understand what you've experienced and how to repeat a + problem. Then we may only be able to assist YOU to debug the problem and to + track down the proper fix. + + We get reports from many people every month and each report can take a + considerable amount of time to really go to the bottom with. + +## How to get a stack trace + + First, you must make sure that you compile all sources with `-g` and that you + don't 'strip' the final executable. Try to avoid optimizing the code as well, + remove `-O`, `-O2` etc from the compiler options. + + Run the program until it cores. + + Run your debugger on the core file, like ` curl + core`. `` should be replaced with the name of your debugger, in + most cases that will be `gdb`, but `dbx` and others also occur. + + When the debugger has finished loading the core file and presents you a + prompt, enter `where` (without quotes) and press return. + + The list that is presented is the stack trace. If everything worked, it is + supposed to contain the chain of functions that were called when curl + crashed. Include the stack trace with your detailed bug report. It'll help a + lot. + +## Bugs in libcurl bindings + + There will of course pop up bugs in libcurl bindings. You should then + primarily approach the team that works on that particular binding and see + what you can do to help them fix the problem. + + If you suspect that the problem exists in the underlying libcurl, then please + convert your program over to plain C and follow the steps outlined above. + +## Bugs in old versions + + The curl project typically releases new versions every other month, and we + fix several hundred bugs per year. For a huge table of releases, number of + bug fixes and more, see: https://curl.haxx.se/docs/releases.html + + The developers in the curl project do not have bandwidth or energy enough to + maintain several branches or to spend much time on hunting down problems in + old versions when chances are we already fixed them or at least that they've + changed nature and appearance in later versions. + + When you experience a problem and want to report it, you really SHOULD + include the version number of the curl you're using when you experience the + issue. If that version number shows us that you're using an out-of-date curl, + you should also try out a modern curl version to see if the problem persists + or how/if it has changed in appearance. + + Even if you cannot immediately upgrade your application/system to run the + latest curl version, you can most often at least run a test version or + experimental build or similar, to get this confirmed or not. + + At times people insist that they cannot upgrade to a modern curl version, but + instead they "just want the bug fixed". That's fine, just don't count on us + spending many cycles on trying to identify which single commit, if that's + even possible, that at some point in the past fixed the problem you're now + experiencing. + + Security wise, it is almost always a bad idea to lag behind the current curl + versions by a lot. We keeping discovering and reporting security problems + over time see you can see in [this + table](https://curl.haxx.se/docs/vulnerabilities.html) + +# Bug fixing procedure + +## What happens on first filing + + When a new issue is posted in the issue tracker or on the mailing list, the + team of developers first need to see the report. Maybe they took the day off, + maybe they're off in the woods hunting. Have patience. Allow at least a few + days before expecting someone to have responded. + + In the issue tracker you can expect that some labels will be set on the issue + to help categorize it. + +## First response + + If your issue/bug report wasn't perfect at once (and few are), chances are + that someone will ask follow-up questions. Which version did you use? Which + options did you use? How often does the problem occur? How can we reproduce + this problem? Which protocols does it involve? Or perhaps much more specific + and deep diving questions. It all depends on your specific issue. + + You should then respond to these follow-up questions and provide more info + about the problem, so that we can help you figure it out. Or maybe you can + help us figure it out. An active back-and-forth communication is important + and the key for finding a cure and landing a fix. + +## Not reproducible + + For problems that we can't reproduce and can't understand even after having + gotten all the info we need and having studied the source code over again, + are really hard to solve so then we may require further work from you who + actually see or experience the problem. + +## Unresponsive + + If the problem haven't been understood or reproduced, and there's nobody + responding to follow-up questions or questions asking for clarifications or + for discussing possible ways to move forward with the task, we take that as a + strong suggestion that the bug is not important. + + Unimportant issues will be closed as inactive sooner or later as they can't + be fixed. The inactivity period (waiting for responses) should not be shorter + than two weeks but may extend months. + +## Lack of time/interest + + Bugs that are filed and are understood can unfortunately end up in the + "nobody cares enough about it to work on it" category. Such bugs are + perfectly valid problems that *should* get fixed but apparently aren't. We + try to mark such bugs as `KNOWN_BUGS material` after a time of inactivity and + if no activity is noticed after yet some time those bugs are added to + `KNOWN_BUGS` and are closed in the issue tracker. + +## `KNOWN_BUGS` + + This is a list of known bugs. Bugs we know exist and that have been pointed + out but that haven't yet been fixed. The reasons for why they haven't been + fixed can involve anything really, but the primary reason is that nobody has + considered these problems to be important enough to spend the necessary time + and effort to have them fixed. + + The `KNOWN_BUGS` are always up for grabs and we will always love the ones who + bring one of them back to live and offers solutions to them. + + The `KNOWN_BUGS` document has a sibling document known as `TODO`. + +## `TODO` + + Issues that are filed or reported that aren't really bugs but more missing + features or ideas for future improvements and so on are marked as + 'enhancement' or 'feature-request' and will be added to the `TODO` document + instead and the issue is closed. We don't keep TODO items in the issue + tracker. + + The `TODO` document is full of ideas and suggestions of what we can add or + fix one day. You're always encouraged and free to grab one of those items and + take up a discussion with the curl development team on how that could be + implemented or provided in the project so that you can work on ticking it odd + that document. + + If the issue is rather a bug and not a missing feature or functionality, it + is listed in `KNOWN_BUGS` instead. + +## Closing off stalled bugs + + The [issue and pull request trackers](https://github.com/curl/curl) only + holds "active" entries open (using a non-precise definition of what active + actually is, but they're at least not completely dead). Those that are + abandoned or in other ways dormant will be closed and sometimes added to + `TODO` and `KNOWN_BUGS` instead. + + This way, we only have "active" issues open on github. Irrelevant issues and + pull requests will not distract developers or casual visitors. diff --git a/docs/Makefile.am b/docs/Makefile.am index da81c9a0a..a8fc9540b 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -45,7 +45,7 @@ EXTRA_DIST = \ ALTSVC.md \ BINDINGS.md \ BUG-BOUNTY.md \ - BUGS \ + BUGS.md \ CHECKSRC.md \ CIPHERS.md \ CMakeLists.txt \ -- cgit v1.2.1