From nobody Wed May 1 00:28:50 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) client-ip=170.10.133.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1658825582; cv=none; d=zohomail.com; s=zohoarc; b=IRlP55BdyWVoYo1exrK00bVkZj933DIzpI1QnpW/n7MHyOh1O24vdPYgj+iYFJktR14OrE3kgwbAQsIXv+PEExaNLWAihhVSQxMwexfHUCSzkxZGZNnZEuYrYmLmt3XooQ2I393oHurpc8f5Mcwbc9OuyekKBmHclYb/MPOZNBs= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1658825582; h=Content-Type:Content-Transfer-Encoding:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=JKdZvz2O8BIzTJNB5FMaxlh8aBVGnaTFr//stOqVZj8=; b=Lr5Z7o0q/lbKhQnh7+jFLo0dMBlfqE/ZeviAEWjKTkTagxL+m4ZHH/Lo/k+isV4aeZ6nzSvtJXHV2pFc1CaF5J6LuAT6+tRP1tq8BHZ4EHKGxyN7kEKIZBlp3psQv2isWScZsiD9YVk9wo22Naay5fVAQ7xAL+w4V54kH+jtCnI= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) by mx.zohomail.com with SMTPS id 1658825582646842.3931513155619; Tue, 26 Jul 2022 01:53:02 -0700 (PDT) Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-512-ERw5jZJiM-ao-BNm-iqivw-1; Tue, 26 Jul 2022 04:52:57 -0400 Received: from smtp.corp.redhat.com (int-mx02.intmail.prod.int.rdu2.redhat.com [10.11.54.2]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id A37A21019E1D; Tue, 26 Jul 2022 08:52:55 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (unknown [10.30.29.100]) by smtp.corp.redhat.com (Postfix) with ESMTP id 906E140D2962; Tue, 26 Jul 2022 08:52:55 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (localhost [IPv6:::1]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id 30C6B1945D89; Tue, 26 Jul 2022 08:52:55 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.rdu2.redhat.com [10.11.54.7]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id D765D1945D86 for ; Tue, 26 Jul 2022 08:52:53 +0000 (UTC) Received: by smtp.corp.redhat.com (Postfix) id AC1601415122; Tue, 26 Jul 2022 08:52:53 +0000 (UTC) Received: from speedmetal.lan (unknown [10.40.208.32]) by smtp.corp.redhat.com (Postfix) with ESMTP id 3F62A141511F for ; Tue, 26 Jul 2022 08:52:53 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1658825580; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=JKdZvz2O8BIzTJNB5FMaxlh8aBVGnaTFr//stOqVZj8=; b=R2Dhx1HyNFEX6nQx2bK/gtLHaZJfrqloTAgIRdEPz73sHBketL0+AXmHU7QI8x3c8E3OF6 zCONk9Z06dYRQBAkQhXcAftkZ0hBwnq1Els0U115LothvQ1WaWOP69XV8ALw+8UTt9xd8M Ge8lBF9Mf1wvSjORVznXsvmtr3+v1kc= X-MC-Unique: ERw5jZJiM-ao-BNm-iqivw-1 X-Original-To: libvir-list@listman.corp.redhat.com From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH v2 1/2] docs: patches: Add a note about reviews and contacting developers Date: Tue, 26 Jul 2022 10:52:50 +0200 Message-Id: <7038f04d98a8190ff5f5d4ce1b43b70571b983cf.1658825473.git.pkrempa@redhat.com> In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.85 on 10.11.54.7 X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.29 Precedence: list List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: libvir-list-bounces@redhat.com Sender: "libvir-list" X-Scanned-By: MIMEDefang 2.84 on 10.11.54.2 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1658825583534100001 Content-Type: text/plain; charset="utf-8" Add a note outling best practices around review and responding to it. Signed-off-by: Peter Krempa Reviewed-by: Erik Skultety --- docs/submitting-patches.rst | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/docs/submitting-patches.rst b/docs/submitting-patches.rst index 7bc22323ee..965e381cc1 100644 --- a/docs/submitting-patches.rst +++ b/docs/submitting-patches.rst @@ -89,3 +89,25 @@ Moreover, such patch needs to be prefixed correctly with ``--subject-prefix=3DPATCHv2`` appended to ``git send-email`` (substitute ``v2`` with the correct version if needed though). + +Reviews +------- + +Reviewing patches may take a lot of effort and review bandwidth is a limit= ed +resource for open source projects. Here are a few rules to follow to strea= mline +the process: + + - **don't** contact individual maintainers/developers directly with your + patches; reviewers are subscribed to the mailing list + - **do** be patient; reviewers may be busy + - **do** respond to reviewer's questions + - **don't** ignore a suggestion from a reviewer; if you disagree discuss = it on + the list before sending a new version + - **do** remind us of your patches on the list if they haven't gotten any + attention for a prolonged period (> week) by replying to your patches w= ith a + "ping" + - **do** test your pathches before sending + +You can also help out by reviewing other patches on the list if you feel +comfortable. Don't hesitate to point out apparent problems in idividual pa= tches, +you are not obliged to review the whole series. --=20 2.36.1 From nobody Wed May 1 00:28:50 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 170.10.129.124 as permitted sender) client-ip=170.10.129.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.129.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1658825582; cv=none; d=zohomail.com; s=zohoarc; b=HXxEow1XCNCuUSLOSgd+1D/5tBOE8mwZbBoP8e/D+GHm2/gD2heWLXmTDv5Hvv2BGZCeq+N/qQ6bhSHQDGMOrbA8puDyOPQVdowK7picX/VfcMXsIdRoxzwXBUId+vnP3tuwggrK/y1lO1Pf7uMy7pHVuKoZC5hZorCvxuohWNo= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1658825582; h=Content-Type:Content-Transfer-Encoding:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=ol2SuFihvVJlhRcxCBfDbtlvF6FznCD2pS+wFnWjZZU=; b=QOreUCcUwTHC5uqYFvPVgVEKt5MAKm1w3uvInPPbXWiW3oNL9iLoPbNKX0y0yfEW1Z6nDEAZvjF6KKSAPl/pCAuAAqr3RDQ+WxUk05S5HgW+dmh3geWWOpuSIyUYfy0sS+xY3s3W0pTBPtsOmQkgsFPJ+BJxkYZRDKjeU9J8DAE= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of redhat.com designates 170.10.129.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) by mx.zohomail.com with SMTPS id 1658825582713740.4406968065209; Tue, 26 Jul 2022 01:53:02 -0700 (PDT) Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id us-mta-623-tsfpApQbMyONEs-OH_6ZTA-1; Tue, 26 Jul 2022 04:52:58 -0400 Received: from smtp.corp.redhat.com (int-mx02.intmail.prod.int.rdu2.redhat.com [10.11.54.2]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 3B691811766; Tue, 26 Jul 2022 08:52:56 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (unknown [10.30.29.100]) by smtp.corp.redhat.com (Postfix) with ESMTP id 29373403D0CA; Tue, 26 Jul 2022 08:52:56 +0000 (UTC) Received: from mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (localhost [IPv6:::1]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id 09D0E1945D89; Tue, 26 Jul 2022 08:52:56 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx07.intmail.prod.int.rdu2.redhat.com [10.11.54.7]) by mm-prod-listman-01.mail-001.prod.us-east-1.aws.redhat.com (Postfix) with ESMTP id AB9DE1945D89 for ; Tue, 26 Jul 2022 08:52:54 +0000 (UTC) Received: by smtp.corp.redhat.com (Postfix) id 8D8CA1415122; Tue, 26 Jul 2022 08:52:54 +0000 (UTC) Received: from speedmetal.lan (unknown [10.40.208.32]) by smtp.corp.redhat.com (Postfix) with ESMTP id 044B6141511F for ; Tue, 26 Jul 2022 08:52:53 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1658825581; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post; bh=ol2SuFihvVJlhRcxCBfDbtlvF6FznCD2pS+wFnWjZZU=; b=RBpyMATYHqb4BysdFTqFn0ZbzAI1kjEB1Xqmk/5avI9zayHrsqwiI/K5QYVOa79wdJoDel A8l2oeIldGODYLVzc7EpOql9uSwc2j7rno5ezc+6aWfDLGpoQcBet6rqxTeG2JbBzpCDzL 41g8ncCig7LLmaic6LDNAJcgdOgwQTs= X-MC-Unique: tsfpApQbMyONEs-OH_6ZTA-1 X-Original-To: libvir-list@listman.corp.redhat.com From: Peter Krempa To: libvir-list@redhat.com Subject: [PATCH v2 2/2] docs: Add article about handling upstream issues Date: Tue, 26 Jul 2022 10:52:51 +0200 Message-Id: In-Reply-To: References: MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.85 on 10.11.54.7 X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.29 Precedence: list List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: libvir-list-bounces@redhat.com Sender: "libvir-list" X-Scanned-By: MIMEDefang 2.84 on 10.11.54.2 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1658825583549100002 Content-Type: text/plain; charset="utf-8" Outline how upstream issues are triaged and explain what the states of the issue means. Signed-off-by: Peter Krempa Reviewed-by: Erik Skultety --- 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 `__ Details on our Continuous Integration +`Upstream issue handling `__ + Outlines the handling of issues and describes the states the issue can = be in. + `Bug reports `__ 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 @@ +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D +Handling of gitlab issues +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D + +.. contents:: + +This document describes the life cycle and handling of upstream gitlab iss= ues. +Issues aggregate bug reports, feature requests, user questions and discuss= ions. + +For members of the project this is a guideline how to handle issues and ho= w 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. Othe= rwise +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 o= f 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 usag= e. + +Discussions - ``kind::discussion`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Any form of discussion which doesn't directly concern any bug or feature r= equest. + +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 **confirm= ed** +state does not necessarily mean that anybody is actively looking to implem= ent +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 whe= ther +the problem would be considered a bug. + +In case of ``kind::enhancement`` issues the **unconfirmed** state is simil= arly +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 deferri= ng 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 re= open +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 reques= t. + 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 tria= ger + 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-mem= bers +of the project don't have permissions to set the labels mentioned above, b= ut +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 comm= ent. + +This will help the project members and they'll do the flag setting afterwa= rds. + +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 wi= ll +volunteer to implement or fix it. We welcome and encourage even draft patc= hes +to implement a feature be sent to the mailing list where it can be discuss= ed +and developed further by the community. + +.. _Untriaged issues: https://gitlab.com/libvirt/libvirt/-/issues/?sort=3D= created_date&state=3Dopened¬%5Blabel_name%5D%5B%5D=3Dstate%3A%3Aunconfir= med¬%5Blabel_name%5D%5B%5D=3Dstate%3A%3Aneedinfo¬%5Blabel_name%5D%5B%= 5D=3Dstate%3A%3Aconfirmed&first_page_size=3D100 +.. _Unconfirmed bugs: https://gitlab.com/libvirt/libvirt/-/issues/?sort=3D= created_date&state=3Dopened&label_name%5B%5D=3Dkind%3A%3Abug&label_name%5B%= 5D=3Dstate%3A%3Aunconfirmed&first_page_size=3D100 +.. _Unconfirmed features: https://gitlab.com/libvirt/libvirt/-/issues/?sor= t=3Dcreated_date&state=3Dopened&label_name%5B%5D=3Dkind%3A%3Aenhancement&la= bel_name%5B%5D=3Dstate%3A%3Aunconfirmed&first_page_size=3D100 +.. _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 =3D [ 'governance', 'hacking', 'hooks', + 'issue-handling', 'java', 'libvirt-go', 'libvirt-go-xml', --=20 2.36.1