Special care is given to preserve the 'quality' anchor in the 'bugs' page as we link to it directly from the gitlab issue template. Signed-off-by: Peter Krempa <pkrempa@xxxxxxxxxx> --- docs/bugs.html.in | 161 ---------------------------------------------- docs/bugs.rst | 125 +++++++++++++++++++++++++++++++++++ docs/meson.build | 2 +- 3 files changed, 126 insertions(+), 162 deletions(-) delete mode 100644 docs/bugs.html.in create mode 100644 docs/bugs.rst diff --git a/docs/bugs.html.in b/docs/bugs.html.in deleted file mode 100644 index 400c423518..0000000000 --- a/docs/bugs.html.in +++ /dev/null @@ -1,161 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE html> -<html xmlns="http://www.w3.org/1999/xhtml";> - <body> - - <h1>Bug reporting</h1> - - <ul id="toc"></ul> - - <h2><a id="security">Security Issues</a></h2> - - <p> - If you think that an issue with libvirt may have security - implications, <strong>please do not</strong> publicly - report it in the bug tracker, mailing lists, or irc. Libvirt - has <a href="securityprocess.html">a dedicated process for handling (potential) security issues</a> - that should be used instead. So if your issue has security - implications, ignore the rest of this page and follow the - <a href="securityprocess.html">security process</a> instead. - </p> - - <h2><a id="bugtracking">Bug Tracking</a></h2> - - <p> - If you are using libvirt binaries from a Linux distribution - check below for distribution specific bug reporting policies - first. - </p> - - <h2><a id="general">General libvirt bug reports</a></h2> - - <p> - Bugs in upstream libvirt code should be reported as issues in the - appropriate <a href="https://gitlab.com/libvirt";>project on GitLab.</a> - Before submitting a ticket, check the existing tickets to see if - the bug/feature is already tracked. - </p> - <p> - It's always a good idea to file bug reports, as the process of - filing the report always makes it easier to describe the - problem, and the bug number provides a quick way of referring to - the problem. However, not everybody in the community pays frequent - attention to issues, so after you file a bug, asking questions - and submitting patches on <a href="contact.html">the libvirt - mailing lists</a> will increase your bug's visibility and - encourage people to think about your problem. Don't hesitate to - ask questions on the list, as others may know of existing - solutions or be interested in collaborating with you on finding - a solution. Patches are always appreciated, and it's likely - that someone else has the same problem you do! - </p> - <p> - If you decide to write code, though, before you begin please - read the <a href="hacking.html">contributor guidelines</a>, - especially the first point: "Discuss any large changes on the - mailing list first. Post patches early and listen to feedback." - Few development experiences are more discouraging than spending - a bunch of time writing a patch only to have someone point out a - better approach on list. - </p> - - <ul> - <li><a href="https://gitlab.com/libvirt/libvirt/-/issues";>View libvirt.git tickets</a></li> - <li><a href="https://gitlab.com/libvirt/libvirt/-/issues/new";>New libvirt.git ticket</a></li> - </ul> - - <p> - Note bugs in language bindings and other sub-projects should be - reported to their corresponding git repository rather than the - main libvirt.git linked above. - </p> - - <h2><a id="distribution">Linux Distribution specific bug reports</a></h2> - <ul> - <li> - If you are using binaries from <strong>Fedora</strong>, enter - tickets against the <code>Fedora</code> product and - the <code>libvirt</code> component. - <ul> - <li><a href="https://bugzilla.redhat.com/buglist.cgi?component=libvirt&product=Fedora";>View Fedora libvirt tickets</a></li> - <li><a href="https://bugzilla.redhat.com/bugzilla/enter_bug.cgi?product=Fedora&component=libvirt";>New Fedora libvirt ticket</a></li> - </ul> - </li> - <li> - <p> - If you are using binaries from <strong>Red Hat Enterprise - Linux</strong>, enter tickets against the Red Hat Enterprise - Linux product that you're using (e.g., Red Hat Enterprise - Linux 6) and the <code>libvirt</code> component. Red Hat - bugzilla has <a href="https://bugzilla.redhat.com";>additional guidance</a> about getting support if - you are a Red Hat customer. - </p> - </li> - <li> - <p> - If you are using binaries from another Linux distribution - first follow their own bug reporting guidelines. - </p> - </li> - <li> - <p> - Finally, if you are a contributor to another Linux - distribution and would like to have your procedure for - filing bugs mentioned here, please mail the libvirt - development list. - </p> - </li> - </ul> - - - <h2><a id="quality">How to file high quality bug reports</a></h2> - - <p> - To increase the likelihood of your bug report being addressed it is - important to provide as much information as possible. When filing - libvirt bugs use this checklist to see if you are providing enough - information: - </p> - - <ul> - <li>The version number of the libvirt build, or SHA1 of the GIT - commit</li> - <li>The hardware architecture being used</li> - <li>The name of the hypervisor (Xen, QEMU, KVM)</li> - <li>The XML config of the guest domain if relevant</li> - <li>For Xen hypervisor, the domain logfiles from /var/log/xen and - /var/log/libvirt/libxl</li> - <li>For QEMU/KVM, the domain logfile from /var/log/libvirt/qemu</li> - </ul> - - <p> - If the bug leads to a tool linked to libvirt crash, then the best - is to provide a backtrace along with the scenario used to get the - crash, the simplest is to run the program under gdb, reproduce the - steps leading to the crash and then issue a gdb "bt -a" command to - get the stack trace, attach it to the bug. Note that for the - data to be really useful libvirt debug information must be present - for example by installing libvirt debuginfo package on Fedora or - Red Hat Enterprise Linux (with debuginfo-install libvirt) prior - to running gdb.</p> - <p> - It may also happen that the libvirt daemon itself crashes or gets stuck, - in the first case run it (as root) under gdb, and reproduce the sequence - leading to the crash, similarly to a normal program provide the - "bt" backtrace information to where gdb will have stopped.<br/> - But if libvirtd gets stuck, for example seems to stop processing - commands, try to attach to the faulty daemon and issue a gdb command - "thread apply all bt" to show all the threads backtraces, as in:</p> - <pre> # ps -o etime,pid `pgrep libvirt` -... note the process id from the output -# gdb /usr/sbin/libvirtd -.... some information about gdb and loading debug data -(gdb) attach $the_daemon_process_id -.... -(gdb) thread apply all bt -.... information to attach to the bug -(gdb) -</pre> - - </body> -</html> diff --git a/docs/bugs.rst b/docs/bugs.rst new file mode 100644 index 0000000000..152d734592 --- /dev/null +++ b/docs/bugs.rst @@ -0,0 +1,125 @@ +.. role:: anchor(raw) + :format: html + +============= +Bug reporting +============= + +.. contents:: + +Security Issues +--------------- + +If you think that an issue with libvirt may have security implications, **please +do not** publicly report it in the bug tracker, mailing lists, or irc. Libvirt +has `a dedicated process for handling (potential) security +issues <securityprocess.html>`__ that should be used instead. So if your issue +has security implications, ignore the rest of this page and follow the `security +process <securityprocess.html>`__ instead. + +Bug Tracking +------------ + +If you are using libvirt binaries from a Linux distribution check below for +distribution specific bug reporting policies first. + +General libvirt bug reports +--------------------------- + +Bugs in upstream libvirt code should be reported as issues in the appropriate +`project on GitLab. <https://gitlab.com/libvirt>`__ Before submitting a ticket, +check the existing tickets to see if the bug/feature is already tracked. + +It's always a good idea to file bug reports, as the process of filing the report +always makes it easier to describe the problem, and the bug number provides a +quick way of referring to the problem. However, not everybody in the community +pays frequent attention to issues, so after you file a bug, asking questions and +submitting patches on `the libvirt mailing lists <contact.html>`__ will increase +your bug's visibility and encourage people to think about your problem. Don't +hesitate to ask questions on the list, as others may know of existing solutions +or be interested in collaborating with you on finding a solution. Patches are +always appreciated, and it's likely that someone else has the same problem you +do! + +If you decide to write code, though, before you begin please read the +`contributor guidelines <hacking.html>`__, especially the first point: "Discuss +any large changes on the mailing list first. Post patches early and listen to +feedback." Few development experiences are more discouraging than spending a +bunch of time writing a patch only to have someone point out a better approach +on list. + +- `View libvirt.git tickets <https://gitlab.com/libvirt/libvirt/-/issues>`__ +- `New libvirt.git ticket <https://gitlab.com/libvirt/libvirt/-/issues/new>`__ + +Note bugs in language bindings and other sub-projects should be reported to +their corresponding git repository rather than the main libvirt.git linked +above. + +Linux Distribution specific bug reports +--------------------------------------- + +- If you are using binaries from **Fedora**, enter tickets against the + ``Fedora`` product and the ``libvirt`` component. + + - `View Fedora libvirt + tickets <https://bugzilla.redhat.com/buglist.cgi?component=libvirt&product=Fedora>`__ + - `New Fedora libvirt + ticket <https://bugzilla.redhat.com/bugzilla/enter_bug.cgi?product=Fedora&component=libvirt>`__ + +- If you are using binaries from **Red Hat Enterprise Linux**, enter tickets + against the Red Hat Enterprise Linux product that you're using (e.g., Red Hat + Enterprise Linux 6) and the ``libvirt`` component. Red Hat bugzilla has + `additional guidance <https://bugzilla.redhat.com>`__ about getting support + if you are a Red Hat customer. + +- If you are using binaries from another Linux distribution first follow their + own bug reporting guidelines. + +- Finally, if you are a contributor to another Linux distribution and would + like to have your procedure for filing bugs mentioned here, please mail the + libvirt development list. + +:anchor:`<a id="quality"/>` + +How to file high quality bug reports +------------------------------------ + +To increase the likelihood of your bug report being addressed it is important to +provide as much information as possible. When filing libvirt bugs use this +checklist to see if you are providing enough information: + +- The version number of the libvirt build, or SHA1 of the GIT commit +- The hardware architecture being used +- The name of the hypervisor (Xen, QEMU, KVM) +- The XML config of the guest domain if relevant +- For Xen hypervisor, the domain logfiles from /var/log/xen and + /var/log/libvirt/libxl +- For QEMU/KVM, the domain logfile from /var/log/libvirt/qemu + +If the bug leads to a tool linked to libvirt crash, then the best is to provide +a backtrace along with the scenario used to get the crash, the simplest is to +run the program under gdb, reproduce the steps leading to the crash and then +issue a gdb "bt -a" command to get the stack trace, attach it to the bug. Note +that for the data to be really useful libvirt debug information must be present +for example by installing libvirt debuginfo package on Fedora or Red Hat +Enterprise Linux (with debuginfo-install libvirt) prior to running gdb. + +| It may also happen that the libvirt daemon itself crashes or gets stuck, in + the first case run it (as root) under gdb, and reproduce the sequence leading + to the crash, similarly to a normal program provide the "bt" backtrace + information to where gdb will have stopped. +| But if libvirtd gets stuck, for example seems to stop processing commands, try + to attach to the faulty daemon and issue a gdb command "thread apply all bt" + to show all the threads backtraces, as in: + +:: + + # ps -o etime,pid `pgrep libvirt` + ... note the process id from the output + # gdb /usr/sbin/libvirtd + .... some information about gdb and loading debug data + (gdb) attach $the_daemon_process_id + .... + (gdb) thread apply all bt + .... information to attach to the bug + (gdb) diff --git a/docs/meson.build b/docs/meson.build index bee7b3e6fc..e92ce6bd9e 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -19,7 +19,6 @@ docs_assets = [ docs_html_in_files = [ '404', - 'bugs', 'cgroups', 'contact', 'csharp', @@ -84,6 +83,7 @@ docs_rst_files = [ 'auth', 'bindings', 'best-practices', + 'bugs', 'ci', 'coding-style', 'committer-guidelines', -- 2.35.1
