mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2024-07-06 18:05:45 +00:00
429c15259c
Outline how upstream issues are triaged and explain what the states of the issue means. Signed-off-by: Peter Krempa <pkrempa@redhat.com> Reviewed-by: Erik Skultety <eskultet@redhat.com>
183 lines
7.4 KiB
ReStructuredText
183 lines
7.4 KiB
ReStructuredText
=========================
|
|
Handling of gitlab issues
|
|
=========================
|
|
|
|
.. contents::
|
|
|
|
This document describes the life cycle and handling of upstream gitlab issues.
|
|
Issue is an aggregate term for 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 imperative we collaboratively keep the issues organized and labeled,
|
|
otherwise we'll end up creating an unnecessary maintenance burden for us.
|
|
|
|
For others, this article should only server as an outline what to expect when
|
|
filing an issue.
|
|
|
|
Types of issues
|
|
---------------
|
|
|
|
Every issue in our GitLab tracker bears the ``kind::`` namespace prefix. Once
|
|
triaged, each issue will have one of the following types assigned to it.
|
|
|
|
Note that issues can be moved freely between the different issue kinds if
|
|
needed.
|
|
|
|
Bugs - ``kind::bug``
|
|
~~~~~~~~~~~~~~~~~~~~
|
|
|
|
This issue describes a flaw in the functionality. The user is expected to
|
|
describe how to reproduce the issue and add `debug logs`_ or a backtrace of all
|
|
daemon threads in case any of the components crashed.
|
|
|
|
Feature requests - ``kind::enhancement``
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
This issue type 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.
|
|
|
|
Detailed technical aspects 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 with issues which don't directly correspond to a flaw or
|
|
a missing feature in the project like usage-related queries.
|
|
|
|
Discussions - ``kind::discussion``
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Any form of discussion which isn't related to any existing bug or feature
|
|
request.
|
|
|
|
States of issues
|
|
----------------
|
|
|
|
States allow project maintainers filtering out issues which need attention, so
|
|
please keep the issue state updated at all times.
|
|
|
|
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 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 the 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 in a timely manner (~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 reporter described the issue sufficiently.
|
|
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 haven't undergone the `Triage process`_ yet.
|
|
|
|
`Unconfirmed bugs`_
|
|
Bugs which should have all the information needed but the initial triager
|
|
couldn't determine nor 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 thus prevent duplicated work.
|
|
|
|
Contribution possibility for non-members of the project
|
|
-------------------------------------------------------
|
|
|
|
Anyone is very welcome to assist in handling and triage of issues.
|
|
|
|
Even though non-members don't have permissions to set the labels mentioned
|
|
above, you can always post a comment to the issue, describing your findings or
|
|
prompt the reporter to provide more information (obviously adhering to the
|
|
`code of conduct`_) or even analyze where the problem lies followed by
|
|
submitting a patch to the mailing list.
|
|
|
|
Someone from the project members will then take care of applying the correct
|
|
label to the issue.
|
|
|
|
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 even welcome and encourage draft patches implementing a feature to be sent
|
|
to the mailing list where they can be discussed and further improved 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
|