[PATCH 07/17] docs: Convert 'bugs' page to rST
Peter Krempa
pkrempa at redhat.com
Mon Mar 7 15:59:27 UTC 2022
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 at redhat.com>
---
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
More information about the libvir-list
mailing list