libvirt/docs/issue-handling.rst

Handling of gitlab issues

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.