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

Outline how upstream issues are triaged and explain what the states of the issue means. Signed-off-by: Peter Krempa <pkrempa(a)redhat.com&gt; --- 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=... +.. _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 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