summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJoshua Powers <josh.powers@canonical.com>2019-12-11 11:44:51 -0800
committerGitHub <noreply@github.com>2019-12-11 11:44:51 -0800
commitd2154f5ca63369aaa3d25ab1db19694af34e23c1 (patch)
treefa55833d7df6c7f7347491c043554945e83c71a0
parenta47405af306219d804ed262d6f7e2039a75883f2 (diff)
parent4c06c2635c7ccba99b7599f34f191b24083f7f8f (diff)
downloadvyos-cloud-init-d2154f5ca63369aaa3d25ab1db19694af34e23c1.tar.gz
vyos-cloud-init-d2154f5ca63369aaa3d25ab1db19694af34e23c1.zip
Merge pull request #95 from powersj/docs/bugs
docs: Add document on how to report bugs
-rw-r--r--doc/rtd/index.rst1
-rw-r--r--doc/rtd/topics/bugs.rst108
2 files changed, 109 insertions, 0 deletions
diff --git a/doc/rtd/index.rst b/doc/rtd/index.rst
index d2662edf..5d90c131 100644
--- a/doc/rtd/index.rst
+++ b/doc/rtd/index.rst
@@ -40,6 +40,7 @@ Having trouble? We would like to help!
topics/boot.rst
topics/cli.rst
topics/faq.rst
+ topics/bugs.rst
.. toctree::
:hidden:
diff --git a/doc/rtd/topics/bugs.rst b/doc/rtd/topics/bugs.rst
new file mode 100644
index 00000000..4b60776b
--- /dev/null
+++ b/doc/rtd/topics/bugs.rst
@@ -0,0 +1,108 @@
+.. _reporting_bugs:
+
+Reporting Bugs
+**************
+
+The following documents:
+
+1) How to collect information for reporting bugs
+2) How to file bugs to the upstream cloud-init project or for distro specific
+ packages
+
+Collect Logs
+============
+
+To aid in debugging, please collect the necessary logs. To do so, run the
+`collect-logs` subcommand to produce a tarfile that you can easily upload:
+
+.. code-block:: shell-session
+
+ $ cloud-init collect-logs
+ Wrote /home/ubuntu/cloud-init.tar.gz
+
+If your version of cloud-init does not have the `collect-logs` subcommand,
+then please manually collect the base log files by doing the following:
+
+.. code-block:: shell-session
+
+ $ dmesg > dmesg.txt
+ $ sudo journalctl -o short-precise > journal.txt
+ $ sudo tar -cvf cloud-init.tar dmesg.txt journal.txt /run/cloud-init \
+ /var/log/cloud-init.log /var/log/cloud-init-output.log
+
+Report Upstream Bug
+===================
+
+Bugs for upstream cloud-init are tracked using Launchpad. To file a bug:
+
+1. Collect the necessary debug logs as described above
+2. `Create a Launchpad account`_ or login to your existing account
+3. `Report an upstream cloud-init bug`_
+
+If debug logs are not provided, you will be asked for them before any
+further time is spent debugging. If you are unable to obtain the required
+logs please explain why in the bug.
+
+If your bug is for a specific distro using cloud-init, please first consider
+reporting it with the upstream distro or confirm that it still occurs
+with the latest upstream cloud-init code. See below for details on specific
+distro reporting.
+
+Distro Specific Issues
+======================
+
+For issues specific to your distro please use one of the following distro
+specific reporting mechanisms:
+
+Ubuntu
+------
+
+To report a bug on Ubuntu use the `ubuntu-bug` command on the affected
+system to automatically collect the necessary logs and file a bug on
+Launchpad:
+
+.. code-block:: shell-session
+
+ $ ubuntu-bug cloud-init
+
+If that does not work or is not an option, please collect the logs using the
+commands in the above Collect Logs section and then report the bug on the
+`Ubuntu bug tracker`_. Make sure to attach your collected logs!
+
+Debian
+------
+
+To file a bug against the Debian package fo cloud-init please use the
+`Debian bug tracker`_ to file against 'Package: cloud-init'. See the
+`Debian bug reporting wiki`_ wiki page for more details.
+
+Red Hat, CentOS, & Fedora
+-------------------------
+
+To file a bug against the Red Hat or Fedora packages of cloud-init please use
+the `Red Hat bugzilla`_.
+
+SUSE & openSUSE
+---------------
+
+To file a bug against the SuSE packages of cloud-init please use the
+`SUSE bugzilla`_.
+
+Arch
+----
+
+To file a bug against the Arch package of cloud-init please use the
+`Arch Linux Bugtracker`_. See the `Arch bug reporting wiki`_ for more
+details.
+
+.. _Create a Launchpad account: https://help.launchpad.net/YourAccount/NewAccount
+.. _Report an upstream cloud-init bug: https://bugs.launchpad.net/cloud-init/+filebug
+.. _Ubuntu bug tracker: https://bugs.launchpad.net/ubuntu/+source/cloud-init/+filebug
+.. _Debian bug tracker: https://bugs.debian.org/cgi-bin/pkgreport.cgi?pkg=cloud-init;dist=unstable
+.. _Debian bug reporting wiki: https://www.debian.org/Bugs/Reporting
+.. _Red Hat bugzilla: https://bugzilla.redhat.com/
+.. _SUSE bugzilla: https://bugzilla.suse.com/index.cgi
+.. _Arch Linux Bugtracker: https://bugs.archlinux.org/
+.. _Arch bug reporting wiki: https://wiki.archlinux.org/index.php/Bug_reporting_guidelines
+
+.. vi: textwidth=79