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

Tue Jul 26 13:07:10 UTC 2022

On Tue, Jul 26, 2022 at 10:52:51AM +0200, Peter Krempa wrote:
> Outline how upstream issues are triaged and explain what the states of
> the issue means.
> 
> Signed-off-by: Peter Krempa <pkrempa at redhat.com>
> ---
>  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.

Outlines the process of handling issues as well as describes the supported
issue types along with their life cycle.

> +
>  `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.

s/Issues/Issue (in GitLab's sense)
s/aggregate/is an aggregate term for

> +
> +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

I don't think a sentence should start with 'Otherwise', how about:

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 it's an outline what to expect when filing an issue.

s/For others/For others,/
s/it's an outline/this article should only server as an outline

> +
> +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.

'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``
> +~~~~~~~~~~~~~~~~~~~~
> +
> +The issue describes a flaw in the functionality. Generally the user should

s/The/This
s/Generally//

'The user is expected to'

> +describe how to reproduce the issue and add `debug logs`_ or a backtrace of all
> +threads in case when any of the components crashed.

s/threads/daemon worker threads
s/when any/any

> +
> +Feature requests - ``kind::enhancement``
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +Issue describes non-existing functionality the user would like to add to

s/^Issue/This issue type/

> +libvirt. Generally the issue should first focus on what the user wants to

s/Generally/Generally,

> +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

s/Technicalities/Detailed technical aspects

> +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.

s/for/with
s/missing/a missing
s/but rather .*$/like usage-related queries

> +
> +Discussions - ``kind::discussion``
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +Any form of discussion which doesn't directly concern any bug or feature request.

s/doesn't directly concern any/isn't related to any existing/

> +
> +States of issues
> +----------------
> +
> +The state of issue helps the maintainers to filter out issues which need

'States allow project maintainers filtering out issues which need attention, so
please keep the issue state updated at all times.'

> +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.

s/general project/project

> +
> +**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

s/if an/if 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

s/Issue/issue

> +``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

s/after sufficient amount of time/in a timely manner (~2 weeks)

> +(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.

s/not available/not available,/

> +
> + * Check whether the reported sufficiently described the problem or request.

s/reported/reporter
s/sufficiently//
s/problem or request/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 didn't undergo the `Triage process`_ yet.

s/didn't undergo/haven't undergone

> +
> +  `Unconfirmed bugs`_
> +    Bugs which should have all the information needed but the initial triager
> +    couldn't determine and confirm the problem.

s/and/nor

> +
> +  `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

s/when/if

> +there's somebody working on it and prevent duplicated work.

s/prevent/thus prevent

> +
> +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.
> +

'Even though non-members don't have...., you can always post a comment to the
issue, describing your findings or prompt the ... where the problem lies
followed by submitting a patch to the mailing list.'

> +This will help the project members and they'll do the flag setting afterwards.

'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 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.

'We even welcome and encourage draft patches implementing a feature to be sent
to the ... where they can be discussed and further improved by the community.'

Couple of nit picks, but:
Reviewed-by: Erik Skultety <eskultet at redhat.com>