[PATCH 07/17] docs: Convert 'bugs' page to rST

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



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&amp;product=Fedora";>View Fedora libvirt tickets</a></li>
-          <li><a href="https://bugzilla.redhat.com/bugzilla/enter_bug.cgi?product=Fedora&amp;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




[Index of Archives]     [Virt Tools]     [Libvirt Users]     [Lib OS Info]     [Fedora Users]     [Fedora Desktop]     [Fedora SELinux]     [Big List of Linux Books]     [Yosemite News]     [KDE Users]     [Fedora Tools]

  Powered by Linux