mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2024-12-22 13:45:38 +00:00
docs: Convert 'bugs' page to rST
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@redhat.com> Reviewed-by: Ján Tomko <jtomko@redhat.com>
This commit is contained in:
Peter Krempa
parent
87b2ede00b
commit
ac5c17a2fb
@ -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>
|
|
||||||
125
docs/bugs.rst
Normal file
125
docs/bugs.rst
Normal file
@ -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)
|
||||||
@ -19,7 +19,6 @@ docs_assets = [
|
|||||||
|
|
||||||
docs_html_in_files = [
|
docs_html_in_files = [
|
||||||
'404',
|
'404',
|
||||||
'bugs',
|
|
||||||
'cgroups',
|
'cgroups',
|
||||||
'contact',
|
'contact',
|
||||||
'csharp',
|
'csharp',
|
||||||
@ -84,6 +83,7 @@ docs_rst_files = [
|
|||||||
'auth',
|
'auth',
|
||||||
'bindings',
|
'bindings',
|
||||||
'best-practices',
|
'best-practices',
|
||||||
|
'bugs',
|
||||||
'ci',
|
'ci',
|
||||||
'coding-style',
|
'coding-style',
|
||||||
'committer-guidelines',
|
'committer-guidelines',
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user