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

Outline how upstream issues are triaged and explain what the states of the issue means.t Signed-off-by: Peter Krempa <pkrempa(a)redhat.com&gt; --- 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=... +.. _Unconfirmed bugs: https://gitlab.com/libvirt/libvirt/-/issues/?sort=created_date&state=... +.. _Unconfirmed features: https://gitlab.com/libvirt/libvirt/-/issues/?sort=created_date&state=... +.. _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