Outline how upstream issues are triaged and explain what the states of
the issue means.
Signed-off-by: Peter Krempa <pkrempa@xxxxxxxxxx>
---
docs/docs.rst | 3 +
docs/issue-handling.rst | 174 ++++++++++++++++++++++++++++++++++++++++
docs/meson.build | 1 +
3 files changed, 178 insertions(+)
create mode 100644 docs/issue-handling.rst
diff --git a/docs/docs.rst b/docs/docs.rst
index 8ca0afdc1a..daba35ca15 100644
--- a/docs/docs.rst
+++ b/docs/docs.rst
@@ -139,6 +139,9 @@ Project development
`CI <ci.html>`__
Details on our Continuous Integration
+`Upstream issue handling <issue-handling.html>`__
+ Outlines the handling of issues and describes the states the issue can be in.
+
`Bug reports <bugs.html>`__
How and where to report bugs and request features
diff --git a/docs/issue-handling.rst b/docs/issue-handling.rst
new file mode 100644
index 0000000000..26f3ff4e40
--- /dev/null
+++ b/docs/issue-handling.rst
@@ -0,0 +1,174 @@
+=========================
+Handling of gitlab issues
+=========================
+
+.. contents::
+
+This document describes the life cycle 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 labeled. 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. With a clear end-goal it's sometimes possible to recommend
+another solution with the same impact.
+
+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 concern 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 and thus deferring it
+to somebody with more knowledge about the code.
+
+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 categorrizing the area of the issue, e.g. ``driver-qemu``,
+ ``virsh``, ``xml`` etc. If an appropriate label is not available add it.
+
+ * Check whether 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 appropriate 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 community.
+
+ `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.
+
+Assigning issues
+----------------
+
+When you plan to address an issue please assign it to yourself to indicate that
+there's somebody working on it and prevent duplicated work.
+
+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 community.
+
+Reporting an issue can be helpful for determining demand and interest or
+reporting a problem, 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¬%5Blabel_name%5D%5B%5D=state%3A%3Aunconfirmed¬%5Blabel_name%5D%5B%5D=state%3A%3Aneedinfo¬%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 0b16d64488..39c60f9034 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -83,6 +83,7 @@ docs_rst_files = [
'governance',
'hacking',
'hooks',
+ 'issue-handling',
'java',
'libvirt-go',
'libvirt-go-xml',
--
2.36.1
