[PATCH 1/1] docs: Add article about handling upstream issues

Peter Krempa pkrempa at redhat.com
Fri May 27 13:30:54 UTC 2022 

Outline how upstream issues are triaged and explain what the states of
the issue means.t

Signed-off-by: Peter Krempa <pkrempa at redhat.com>
---
 docs/docs.rst           |   3 +
 docs/issue-handling.rst | 164 ++++++++++++++++++++++++++++++++++++++++
 docs/meson.build        |   1 +
 3 files changed, 168 insertions(+)
 create mode 100644 docs/issue-handling.rst

diff --git a/docs/docs.rst b/docs/docs.rst
index 0a698913be..a4d44cb4c7 100644
--- a/docs/docs.rst
+++ b/docs/docs.rst
@@ -136,6 +136,9 @@ Project development
 `Project strategy <strategy.html>`__
    Sets a vision for future direction & technical choices

+`Upstream issue handling <issue-handling.html>`__
+   Outlines the handling of issues and describes the states the issue can be in.
+
 `CI Testing <ci.html>`__
    Details of the Continuous Integration testing strategy

diff --git a/docs/issue-handling.rst b/docs/issue-handling.rst
new file mode 100644
index 0000000000..41cf836a15
--- /dev/null
+++ b/docs/issue-handling.rst
@@ -0,0 +1,164 @@
+=========================
+Handling of gitlab issues
+=========================
+
+.. contents::
+
+This document describes the lifecycle and handling of upstream gitlab issues.
+Issues aggregate bug reports, feature requests, user questions and discussions.
+
+For members of the project this is a guideline how to handle issues and how to
+transition them between states based on the interaction with the reporter.
+
+It is important that we try to keep the issues organized and labelled. Otherwise
+it's not pleasant to go through everything and try to weed out and fix once
+
+For others it's an outline what to expect when filing an issue.
+
+Types of issues
+---------------
+
+Generally we use the following issue types based on the individual request. A
+gitlab *scoped label* of the ``kind::`` set is used to label the type of an
+issue. Each issue should have one of these once it's triaged.
+
+Issues can be freely moved between various kinds if needed.
+
+Bugs - ``kind::bug``
+~~~~~~~~~~~~~~~~~~~~
+
+The issue describes a flaw in the functionality. Generally the user should
+describe how to reproduce the issue and add `debug logs`_ or a backtrace of all
+threads in case when any of the components crashed.
+
+Feature requests - ``kind::enhancement``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Issue describes non-existing functionality the user would like to add to
+libvirt. Generally the issue should first focus on what the user wants to
+achieve rather than any form of technical detail so that it's obvious what
+the end goal is. Technicalities can be described later but should not be the
+main focus of the initial report.
+
+User support queries - ``kind::support``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This label is used for issues which don't directly correspond to a flaw or
+missing feature in the project but rather outline a users query about usage.
+
+Discussions - ``kind::discussion``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Any form of discussion which doesn't directly concert any bug or feature request.
+
+States of issues
+----------------
+
+The state of issue helps the maintainers to filter out issues which need
+attention, thus please update the state as appropriate.
+
+Confirmed issues - ``state::confirmed``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In case of ``kind::bug`` issues the **confirmed** state means that there is
+a real problem with the functionality and there is (seemingly) enough
+information to figure out where the problem is and fix it.
+
+``kind::enhancement`` issues should be marked as **confirmed** as long as the
+general idea of the required functionality makes sense and would be in line
+of the general project strategy.
+
+**Note:** Unless the issue is assigned to a specific person, the **confirmed**
+state does not necessarily mean that anybody is actively looking to implement
+the functionality or fix the problem. See the `disclaimer`_.
+
+Unconfirmed issues - ``state::unconfirmed``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``kind::bug`` issues are considered **unconfirmed** when there is seemingly
+enough information describing the problem, but the triager is not sure whether
+the problem would be considered a bug.
+
+In case of ``kind::enhancement`` issues the **unconfirmed** state is similarly
+used for feature requests which might not make sense.
+
+In general use of the **unconfirmed** state should be avoided if possible,
+although if an initial triager requests all necessary information from the
+reporter, but is not sure about the issue itself it's okay to defer it to
+somebody else by setting the ``state::unconfirmed`` label.
+
+Issues needing additional information from reporter - ``state::needinfo``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If additional information is requested from the reporter of the Issue the
+``state:needinfo`` label should be added, so that the issues can be easily
+filtered.
+
+If the reporter doesn't respond to the request after sufficient amount of time
+(at least 2 weeks) the issue should be closed prompting the reporter to reopen
+once they provide the required information.
+
+Triage process
+--------------
+
+The following steps should be applied to any new issue reported.
+
+ * Set the labels categrorizing the area of the issue, e.g. ``driver-qemu``,
+   ``virsh``, ``xml`` etc. If an appropriate label is not available add it.
+
+ * Check wheter the reported sufficiently described the problem or request.
+   If something is missing or unclear, ask for additional data and set
+   ``state::needinfo``.
+
+ * Once all requested information is provided set the appriate state:
+    - ``state::confirmed`` if you are certain where the bug is or that the
+      feature request makes sense
+    - ``state::unconfirmed`` to defer the investigation to somebody else
+
+Issues needing attention
+------------------------
+
+The following gitlab search queries provide lists of issues which require
+attention from the upstream comunity.
+
+  `Untriaged issues`_
+    Issues which didn't undergo the `Triage process`_ yet.
+
+  `Unconfirmed bugs`_
+    Bugs which should have all the information needed but the initial triager
+    couldn't determine and confirm the problem.
+
+  `Unconfirmed features`_
+    Feature requests having the proper description of the request but it's not
+    yet clear whether the feature makes sense.
+
+Contribution possibility for non-members of the project
+-------------------------------------------------------
+
+Anyone is very welcome to assist in handling and triage of issues. Non-members
+of the project don't have permissions to set the labels mentioned above, but
+that is not a problem. You can always describe your findings, prompt the
+reporter to provide more information (obviously adhering to the
+`code of conduct`_) or even analyze where the problem lies and post a comment.
+
+This will help the project members and they'll do the flag setting afterwards.
+
+Disclaimer
+----------
+
+Please note that libvirt, like most open source projects, relies on
+contributors who have motivation, skills and available time to work on
+implementing particular features or fixing bugs as well as assisting the
+upstream comunity.
+
+Reporting an issue can be helpful for determining demand and interest or
+reporting a probllem,  but doing so is not a guarantee that a contributor will
+volunteer to implement or fix it. We welcome and encourage even draft patches
+to implement a feature be sent to the mailing list where it can be discussed
+and developed further by the community.
+
+.. _Untriaged issues: https://gitlab.com/libvirt/libvirt/-/issues/?sort=created_date&state=opened&not%5Blabel_name%5D%5B%5D=state%3A%3Aunconfirmed&not%5Blabel_name%5D%5B%5D=state%3A%3Aneedinfo&not%5Blabel_name%5D%5B%5D=state%3A%3Aconfirmed&first_page_size=100
+.. _Unconfirmed bugs: https://gitlab.com/libvirt/libvirt/-/issues/?sort=created_date&state=opened&label_name%5B%5D=kind%3A%3Abug&label_name%5B%5D=state%3A%3Aunconfirmed&first_page_size=100
+.. _Unconfirmed features: https://gitlab.com/libvirt/libvirt/-/issues/?sort=created_date&state=opened&label_name%5B%5D=kind%3A%3Aenhancement&label_name%5B%5D=state%3A%3Aunconfirmed&first_page_size=100
+.. _debug logs: https://libvirt.org/kbase/debuglogs.html
+.. _code of conduct: governance.html#code-of-conduct
diff --git a/docs/meson.build b/docs/meson.build
index d71f6006dd..d93eaa6355 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -81,6 +81,7 @@ docs_rst_files = [
   'governance',
   'hacking',
   'hooks',
+  'issue-handling',
   'java',
   'libvirt-go',
   'libvirt-go-xml',
-- 
2.35.3

More information about the libvir-list mailing list