From nobody Wed May 1 10:44:54 2024 Delivered-To: importer@patchew.org Received-SPF: none (zoho.com: 192.237.175.120 is neither permitted nor denied by domain of lists.xenproject.org) client-ip=192.237.175.120; envelope-from=xen-devel-bounces@lists.xenproject.org; helo=lists.xenproject.org; Authentication-Results: mx.zohomail.com; spf=none (zoho.com: 192.237.175.120 is neither permitted nor denied by domain of lists.xenproject.org) smtp.mailfrom=xen-devel-bounces@lists.xenproject.org ARC-Seal: i=1; a=rsa-sha256; t=1569557986; cv=none; d=zoho.com; s=zohoarc; b=MNpfF6807QWcVEFkDkIiIRjuhUQW4bfP+rv4x2ZGaB4gngxC4NpxeY5dkJs7jvkmSPEkV1Ppx9z//I2p5cbl/Q1OPzt+GTjxKMWL3l6akCSf3gLCTu/oSdXJvAAJ3xiX4N43LxT6GkxDDqjXOZ6s2KpQnbdF9KtEVJVpjaznGDg= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zoho.com; s=zohoarc; t=1569557986; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To:ARC-Authentication-Results; bh=cprs6M1rL2MljAoBn1a+4GZwoCh90z08BeLri1cczNU=; b=bRNEqGb/f8Dx9DFZSx42H0Z6Zsz3gzTJrFiGtMqWU2YkTeDrmDn+PS8qi3gFo4addokmVwtNaUWfGn7ADMkKU83H62c2h00ENio+XJcvgLYk6HtW5Wsz5Zf1umHMZeLXz4YwT1U4etdMkam8YGblXW5amBqKsqQHaekUDWl2yAg= ARC-Authentication-Results: i=1; mx.zoho.com; spf=none (zoho.com: 192.237.175.120 is neither permitted nor denied by domain of lists.xenproject.org) smtp.mailfrom=xen-devel-bounces@lists.xenproject.org Return-Path: Received: from lists.xenproject.org (lists.xenproject.org [192.237.175.120]) by mx.zohomail.com with SMTPS id 1569557986499419.74244902709233; Thu, 26 Sep 2019 21:19:46 -0700 (PDT) Received: from localhost ([127.0.0.1] helo=lists.xenproject.org) by lists.xenproject.org with esmtp (Exim 4.89) (envelope-from ) id 1iDhiO-0003DU-9B; Fri, 27 Sep 2019 04:18:44 +0000 Received: from us1-rack-iad1.inumbo.com ([172.99.69.81]) by lists.xenproject.org with esmtp (Exim 4.89) (envelope-from ) id 1iDZcL-0000j1-5f for xen-devel@lists.xenproject.org; Thu, 26 Sep 2019 19:39:57 +0000 Received: from mail.xenproject.org (unknown [104.130.215.37]) by localhost (Halon) with ESMTPS id 5df395ee-e095-11e9-97fb-bc764e2007e4; Thu, 26 Sep 2019 19:39:34 +0000 (UTC) Received: from xenbits.xenproject.org ([104.239.192.120]) by mail.xenproject.org with esmtp (Exim 4.89) (envelope-from ) id 1iDZbu-0002GK-FL; Thu, 26 Sep 2019 19:39:30 +0000 Received: from localhost ([127.0.0.1] helo=MacBook-Pro-2.Home) by xenbits.xenproject.org with esmtp (Exim 4.89) (envelope-from ) id 1iDZbu-0007uS-6D; Thu, 26 Sep 2019 19:39:30 +0000 X-Inumbo-ID: 5df395ee-e095-11e9-97fb-bc764e2007e4 From: Lars Kurth To: xen-devel@lists.xenproject.org Date: Thu, 26 Sep 2019 20:39:19 +0100 Message-Id: <00c6c80b12b1d201d7140626c7efe9d75645dee9.1569525222.git.lars.kurth@citrix.com> X-Mailer: git-send-email 2.13.0 In-Reply-To: References: In-Reply-To: References: X-Mailman-Approved-At: Fri, 27 Sep 2019 04:18:43 +0000 Subject: [Xen-devel] [PATCH v2 1/6] Import v1.4 of Contributor Covenant CoC X-BeenThere: xen-devel@lists.xenproject.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: Xen developer discussion List-Unsubscribe: , List-Post: List-Help: List-Subscribe: , Cc: Lars Kurth , xen-api@lists.xenproject.org, minios-devel@lists.xenproject.org, committers@xenproject.org, mirageos-devel@lists.xenproject.org, win-pv-devel@lists.xenproject.org MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Errors-To: xen-devel-bounces@lists.xenproject.org Sender: "Xen-devel" From: Lars Kurth Signed-off-by: Lars Kurth --- Cc: minios-devel@lists.xenproject.org Cc: xen-api@lists.xenproject.org Cc: win-pv-devel@lists.xenproject.org Cc: mirageos-devel@lists.xenproject.org Cc: committers@xenproject.org --- code-of-conduct.md | 76 ++++++++++++++++++++++++++++++++++++++++++++++++++= ++++ 1 file changed, 76 insertions(+) create mode 100644 code-of-conduct.md diff --git a/code-of-conduct.md b/code-of-conduct.md new file mode 100644 index 0000000..81b217c --- /dev/null +++ b/code-of-conduct.md @@ -0,0 +1,76 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +In the interest of fostering an open and welcoming environment, we as +contributors and maintainers pledge to make participation in our project a= nd +our community a harassment-free experience for everyone, regardless of age= , body +size, disability, ethnicity, sex characteristics, gender identity and expr= ession, +level of experience, education, socio-economic status, nationality, person= al +appearance, race, religion, or sexual identity and orientation. + +## Our Standards + +Examples of behavior that contributes to creating a positive environment +include: + +* Using welcoming and inclusive language +* Being respectful of differing viewpoints and experiences +* Gracefully accepting constructive criticism +* Focusing on what is best for the community +* Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +* The use of sexualized language or imagery and unwelcome sexual attention= or + advances +* Trolling, insulting/derogatory comments, and personal or political attac= ks +* Public or private harassment +* Publishing others' private information, such as a physical or electronic + address, without explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Our Responsibilities + +Project maintainers are responsible for clarifying the standards of accept= able +behavior and are expected to take appropriate and fair corrective action in +response to any instances of unacceptable behavior. + +Project maintainers have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other contributions +that are not aligned to this Code of Conduct, or to ban temporarily or +permanently any contributor for other behaviors that they deem inappropria= te, +threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies within all project spaces, and it also applie= s when +an individual is representing the project or its community in public space= s. +Examples of representing a project or community include using an official +project e-mail address, posting via an official social media account, or a= cting +as an appointed representative at an online or offline event. Representati= on of +a project may be further defined and clarified by project maintainers. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported by contacting the project team at [INSERT EMAIL ADDRESS]. All +complaints will be reviewed and investigated and will result in a response= that +is deemed necessary and appropriate to the circumstances. The project team= is +obligated to maintain confidentiality with regard to the reporter of an in= cident. +Further details of specific enforcement policies may be posted separately. + +Project maintainers who do not follow or enforce the Code of Conduct in go= od +faith may face temporary or permanent repercussions as determined by other +members of the project's leadership. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage],= version 1.4, +available at https://www.contributor-covenant.org/version/1/4/code-of-cond= uct.html + +[homepage]: https://www.contributor-covenant.org + +For answers to common questions about this code of conduct, see +https://www.contributor-covenant.org/faq --=20 2.13.0 _______________________________________________ Xen-devel mailing list Xen-devel@lists.xenproject.org https://lists.xenproject.org/mailman/listinfo/xen-devel From nobody Wed May 1 10:44:54 2024 Delivered-To: importer@patchew.org Received-SPF: none (zoho.com: 192.237.175.120 is neither permitted nor denied by domain of lists.xenproject.org) client-ip=192.237.175.120; envelope-from=xen-devel-bounces@lists.xenproject.org; helo=lists.xenproject.org; Authentication-Results: mx.zohomail.com; spf=none (zoho.com: 192.237.175.120 is neither permitted nor denied by domain of lists.xenproject.org) smtp.mailfrom=xen-devel-bounces@lists.xenproject.org ARC-Seal: i=1; a=rsa-sha256; t=1569557987; cv=none; d=zoho.com; s=zohoarc; b=FgqxSpcP8l2HrTNtExIEsDsBECssA7gp6nN0X8GFObfOXnMp3LNdmYt0tRekZ16/qddicApUWr1ZNZ8vPsMV1q/uru1MwMBFfQajLjUkSWQlmYMHX5QCSlUI9uRC10wONsDlrW7+T79sScGUn2xYzoh/wXYz/UUMyaH6Bqc+yj4= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zoho.com; s=zohoarc; t=1569557987; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To:ARC-Authentication-Results; bh=970slV8pFtUtIxctanr2ISixznuvwTjZPiLOKSEmuyU=; b=mtlv5I1hn7gKPq4Y++lzCC6q4uiP3QHNfcfdgLsHwT1G/obDEaMTtPnylNml5xZryq9VWUytC2SECscZDQwa/uKfRT51KF+zUTJM3AScGJ/A4kKfXBw/D6xIEL5KB7aLuJnHWFdH/UuT7WSe/h4f8A0zEuIbsRtcZo5aAkSFGM8= ARC-Authentication-Results: i=1; mx.zoho.com; spf=none (zoho.com: 192.237.175.120 is neither permitted nor denied by domain of lists.xenproject.org) smtp.mailfrom=xen-devel-bounces@lists.xenproject.org Return-Path: Received: from lists.xenproject.org (lists.xenproject.org [192.237.175.120]) by mx.zohomail.com with SMTPS id 1569557987374591.8865821577924; Thu, 26 Sep 2019 21:19:47 -0700 (PDT) Received: from localhost ([127.0.0.1] helo=lists.xenproject.org) by lists.xenproject.org with esmtp (Exim 4.89) (envelope-from ) id 1iDhiP-0003Eb-9V; Fri, 27 Sep 2019 04:18:45 +0000 Received: from us1-rack-iad1.inumbo.com ([172.99.69.81]) by lists.xenproject.org with esmtp (Exim 4.89) (envelope-from ) id 1iDZd4-0001Pl-8l for xen-devel@lists.xenproject.org; Thu, 26 Sep 2019 19:40:42 +0000 Received: from mail.xenproject.org (unknown [104.130.215.37]) by localhost (Halon) with ESMTPS id 5f5ca010-e095-11e9-bf31-bc764e2007e4; Thu, 26 Sep 2019 19:39:36 +0000 (UTC) Received: from xenbits.xenproject.org ([104.239.192.120]) by mail.xenproject.org with esmtp (Exim 4.89) (envelope-from ) id 1iDZbv-0002GQ-Go; Thu, 26 Sep 2019 19:39:31 +0000 Received: from localhost ([127.0.0.1] helo=MacBook-Pro-2.Home) by xenbits.xenproject.org with esmtp (Exim 4.89) (envelope-from ) id 1iDZbv-0007uS-7i; Thu, 26 Sep 2019 19:39:31 +0000 X-Inumbo-ID: 5f5ca010-e095-11e9-bf31-bc764e2007e4 From: Lars Kurth To: xen-devel@lists.xenproject.org Date: Thu, 26 Sep 2019 20:39:20 +0100 Message-Id: <469326764ec7da37796adf429d61173207798816.1569525222.git.lars.kurth@citrix.com> X-Mailer: git-send-email 2.13.0 In-Reply-To: References: In-Reply-To: References: X-Mailman-Approved-At: Fri, 27 Sep 2019 04:18:43 +0000 Subject: [Xen-devel] [PATCH v2 2/6] Xen Project Code of Conduct X-BeenThere: xen-devel@lists.xenproject.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: Xen developer discussion List-Unsubscribe: , List-Post: List-Help: List-Subscribe: , Cc: Lars Kurth , xen-api@lists.xenproject.org, minios-devel@lists.xenproject.org, committers@xenproject.org, mirageos-devel@lists.xenproject.org, win-pv-devel@lists.xenproject.org MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Errors-To: xen-devel-bounces@lists.xenproject.org Sender: "Xen-devel" From: Lars Kurth Specific changes to the baseline: * Replace list of positive behaviors with link to separate process * Replace maintainers with project leadership (except in our pledge where maintainers is more appropriate) * Add 'of all sub-projects' to clarify scope of CoC * Rename Enforcement * Replace "project team" with "Conduct Team members" * Add e-mail alias * Add section on contacting individual Conduct Team members * Add section on Conduct Team members Signed-off-by: Lars Kurth --- Chagges since v1: * Addressed newline changes Cc: minios-devel@lists.xenproject.org Cc: xen-api@lists.xenproject.org Cc: win-pv-devel@lists.xenproject.org Cc: mirageos-devel@lists.xenproject.org Cc: committers@xenproject.org --- code-of-conduct.md | 45 ++++++++++++++++++++++++++++----------------- 1 file changed, 28 insertions(+), 17 deletions(-) diff --git a/code-of-conduct.md b/code-of-conduct.md index 81b217c..5d6d1d5 100644 --- a/code-of-conduct.md +++ b/code-of-conduct.md @@ -1,4 +1,4 @@ -# Contributor Covenant Code of Conduct +# Xen Project Code of Conduct =20 ## Our Pledge =20 @@ -11,14 +11,10 @@ appearance, race, religion, or sexual identity and orie= ntation. =20 ## Our Standards =20 -Examples of behavior that contributes to creating a positive environment -include: - -* Using welcoming and inclusive language -* Being respectful of differing viewpoints and experiences -* Gracefully accepting constructive criticism -* Focusing on what is best for the community -* Showing empathy towards other community members +We believe that a Code of Conduct can help create a harassment-free enviro= nment, +but is not sufficient to create a welcoming environment on its own: guidan= ce on +creating a welcoming environment, how to communicate in an effective and f= riendly +way, etc. can be found [here](communication-guide.md). =20 Examples of unacceptable behavior by participants include: =20 @@ -33,11 +29,11 @@ Examples of unacceptable behavior by participants inclu= de: =20 ## Our Responsibilities =20 -Project maintainers are responsible for clarifying the standards of accept= able +Project leadership team members are responsible for clarifying the standar= ds of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior. =20 -Project maintainers have the right and responsibility to remove, edit, or +Project leadership team members have the right and responsibility to remov= e, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropria= te, @@ -45,26 +41,41 @@ threatening, offensive, or harmful. =20 ## Scope =20 -This Code of Conduct applies within all project spaces, and it also applie= s when +This Code of Conduct applies within all project spaces of all sub-projects= , and it also applies when an individual is representing the project or its community in public space= s. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or a= cting as an appointed representative at an online or offline event. Representati= on of -a project may be further defined and clarified by project maintainers. +a project may be further defined and clarified by the project leadership. =20 -## Enforcement +## What to do if you witness or are subject to unacceptable behavior =20 Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported by contacting the project team at [INSERT EMAIL ADDRESS]. All +reported by contacting Conduct Team members at conduct@xenproject.org. All complaints will be reviewed and investigated and will result in a response= that -is deemed necessary and appropriate to the circumstances. The project team= is +is deemed necessary and appropriate to the circumstances. Conduct Team mem= bers are obligated to maintain confidentiality with regard to the reporter of an in= cident. Further details of specific enforcement policies may be posted separately. =20 -Project maintainers who do not follow or enforce the Code of Conduct in go= od +If you have concerns about any of the members of the conduct@ alias, +you are welcome to contact precisely the Conduct Team member(s) of +your choice. + +Project leadership team members who do not follow or enforce the Code of C= onduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership. =20 +## Conduct Team members +Conduct Team members are project leadership team members from any +sub-project. The current list of Conduct Team members is: +* Lars Kurth +* George Dunlap +* Ian Jackson + +Conduct Team members are changed by proposing a change to this document, +posted on all sub-project lists, followed by a formal global vote as outli= ned +[here]: https://xenproject.org/developers/governance/#project-decisions + ## Attribution =20 This Code of Conduct is adapted from the [Contributor Covenant][homepage],= version 1.4, --=20 2.13.0 _______________________________________________ Xen-devel mailing list Xen-devel@lists.xenproject.org https://lists.xenproject.org/mailman/listinfo/xen-devel From nobody Wed May 1 10:44:54 2024 Delivered-To: importer@patchew.org Received-SPF: none (zoho.com: 192.237.175.120 is neither permitted nor denied by domain of lists.xenproject.org) client-ip=192.237.175.120; envelope-from=xen-devel-bounces@lists.xenproject.org; helo=lists.xenproject.org; Authentication-Results: mx.zohomail.com; spf=none (zoho.com: 192.237.175.120 is neither permitted nor denied by domain of lists.xenproject.org) smtp.mailfrom=xen-devel-bounces@lists.xenproject.org ARC-Seal: i=1; a=rsa-sha256; t=1569557984; cv=none; d=zoho.com; s=zohoarc; b=Agaf9FGfNE2rhy6fcJdd4MtqgNkVVCVepoZn+1BCfX9VMBdSaVa+XaPSK6cGnXzbHKfndCvu2pOMMDbcboMVHpErKbcXuC4XLAFThF1l7RGuEtTklSVQW/vJHqHebI2YdxP10QDzOt3M68iVx8hA+jwxpap6zD3Gvs822E1bWAY= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zoho.com; s=zohoarc; t=1569557984; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To:ARC-Authentication-Results; bh=GjZg7RIedB9bceLe2xSzuS8ifQB5oW2rnui69kYvjho=; b=HM8aYHF7mtGrHYBRtUlpHYnRxGhpX+MGiLiphIsjycjEk4JmArD6tHkDy+7JUckyICeSKHG1lJ7oH/JHYnl0WkuEffpGgi33ntSk7FvAVOCxnwgi/s6+bcKLWXajDdnksrWG5VGYm84GsNn8OsSdA8jvGJDT8pTALjdWCdYKLes= ARC-Authentication-Results: i=1; mx.zoho.com; spf=none (zoho.com: 192.237.175.120 is neither permitted nor denied by domain of lists.xenproject.org) smtp.mailfrom=xen-devel-bounces@lists.xenproject.org Return-Path: Received: from lists.xenproject.org (lists.xenproject.org [192.237.175.120]) by mx.zohomail.com with SMTPS id 1569557984148718.3074011379031; Thu, 26 Sep 2019 21:19:44 -0700 (PDT) Received: from localhost ([127.0.0.1] helo=lists.xenproject.org) by lists.xenproject.org with esmtp (Exim 4.89) (envelope-from ) id 1iDhiO-0003Dj-JS; Fri, 27 Sep 2019 04:18:44 +0000 Received: from us1-rack-iad1.inumbo.com ([172.99.69.81]) by lists.xenproject.org with esmtp (Exim 4.89) (envelope-from ) id 1iDZcf-0001Ma-76 for xen-devel@lists.xenproject.org; Thu, 26 Sep 2019 19:40:17 +0000 Received: from mail.xenproject.org (unknown [104.130.215.37]) by localhost (Halon) with ESMTPS id 5e9b17ba-e095-11e9-bf31-bc764e2007e4; Thu, 26 Sep 2019 19:39:35 +0000 (UTC) Received: from xenbits.xenproject.org ([104.239.192.120]) by mail.xenproject.org with esmtp (Exim 4.89) (envelope-from ) id 1iDZbw-0002GZ-Ex; Thu, 26 Sep 2019 19:39:32 +0000 Received: from localhost ([127.0.0.1] helo=MacBook-Pro-2.Home) by xenbits.xenproject.org with esmtp (Exim 4.89) (envelope-from ) id 1iDZbw-0007uS-94; Thu, 26 Sep 2019 19:39:32 +0000 X-Inumbo-ID: 5e9b17ba-e095-11e9-bf31-bc764e2007e4 From: Lars Kurth To: xen-devel@lists.xenproject.org Date: Thu, 26 Sep 2019 20:39:21 +0100 Message-Id: <117840fe5ad0eea191335c942b61ff8b23b4b01b.1569525222.git.lars.kurth@citrix.com> X-Mailer: git-send-email 2.13.0 In-Reply-To: References: MIME-Version: 1.0 In-Reply-To: References: X-Mailman-Approved-At: Fri, 27 Sep 2019 04:18:43 +0000 Subject: [Xen-devel] [PATCH v2 3/6] Add Communication Guide X-BeenThere: xen-devel@lists.xenproject.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: Xen developer discussion List-Unsubscribe: , List-Post: List-Help: List-Subscribe: , Cc: Lars Kurth , xen-api@lists.xenproject.org, minios-devel@lists.xenproject.org, committers@xenproject.org, mirageos-devel@lists.xenproject.org, win-pv-devel@lists.xenproject.org Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Errors-To: xen-devel-bounces@lists.xenproject.org Sender: "Xen-devel" From: Lars Kurth This document is a portal page that lays out our gold standard, best practices for some common situations and mechanisms to help resolve issues that can have a negative effect on our community. Detail is covered in subsequent documents Signed-off-by: Lars Kurth --- Cc: minios-devel@lists.xenproject.org Cc: xen-api@lists.xenproject.org Cc: win-pv-devel@lists.xenproject.org Cc: mirageos-devel@lists.xenproject.org Cc: committers@xenproject.org --- communication-guide.md | 67 ++++++++++++++++++++++++++++++++++++++++++++++= ++++ 1 file changed, 67 insertions(+) create mode 100644 communication-guide.md diff --git a/communication-guide.md b/communication-guide.md new file mode 100644 index 0000000..4bcf440 --- /dev/null +++ b/communication-guide.md @@ -0,0 +1,67 @@ +# Communication Guide + +We believe that our [Code of Conduct] (code-of-conduct.md) can help create= a +harassment-free environment, but is not sufficient to create a welcoming +environment on its own. We can all make mistakes: when we do, we take +responsibility for them and try to improve. + +This document lays out our gold standard, best practices for some common +situations and mechanisms to help resolve issues that can have a +negative effect on our community. + +## Goal + +We want a productive, welcoming and agile community that can welcome new +ideas in a complex technical field which is able to reflect on and improve= how we +work. + +## Communication & Handling Differences in Opinions + +Examples of behavior that contributes to creating a positive environment +include: +* Use welcoming and inclusive language +* Keep discussions technical and actionable +* Be respectful of differing viewpoints and experiences +* Be aware of your own and counterpart=E2=80=99s communication style and c= ulture +* Gracefully accept constructive criticism +* Focus on what is best for the community +* Show empathy towards other community members +* Resolve differences in opinion effectively + +## Getting Help + +When developing code collaboratively, technical discussion and disagreemen= ts +are unavoidable. Our contributors come from different countries and cultur= es, +are driven by different goals and take pride in their work and in their po= int +of view. This invariably can lead to lengthy and unproductive debate, +followed by indecision, sometimes this can impact working relationships +or lead to other issues that can have a negative effect on our community. + +To minimize such issue, we provide a 3-stage process +* Self-help as outlined in this document +* Ability to ask for an independent opinion or help in private +* Mediation between parties which disagree. In this case a neutral communi= ty + member assists the disputing parties resolve the issues or will work wit= h the + parties such that they can improve future interactions. + +If you need and independent opinion or help, feel free to contact +mediation@xenproject.org. The team behind mediation@ is made up of the +same community members as those listed in the Conduct Team: see +[Code of Conduct](code-of-conduct.md). In addition, team members are oblig= ated +to maintain confidentiality with regard discussions that take place. If you +have concerns about any of the members of the mediation@ alias, you are +welcome to contact precisely the team member(s) of your choice. In this ca= se, +please make certain that you highlight the nature of a request by making s= ure that +either help or mediation is mentioned in the e-mail subject or body. + +## Specific Topics and Best Practice + +* [Code Review Guide] (code-review-guide.md): + Essential reading for code reviewers and contributors +* [Communication Best Practice] (communication-practice.md): + This guide covers communication guidelines for code reviewers and review= ees. It + should help you create self-awareness, anticipate, avoid and help resol= ve + communication issues. +* [Resolving Disagreement] (resolving-disagreement.md): + This guide lays out common situations that can lead to dead-lock and sho= ws common + patterns on how to avoid and resolve issues. --=20 2.13.0 _______________________________________________ Xen-devel mailing list Xen-devel@lists.xenproject.org https://lists.xenproject.org/mailman/listinfo/xen-devel From nobody Wed May 1 10:44:54 2024 Delivered-To: importer@patchew.org Received-SPF: none (zoho.com: 192.237.175.120 is neither permitted nor denied by domain of lists.xenproject.org) client-ip=192.237.175.120; envelope-from=xen-devel-bounces@lists.xenproject.org; helo=lists.xenproject.org; Authentication-Results: mx.zohomail.com; spf=none (zoho.com: 192.237.175.120 is neither permitted nor denied by domain of lists.xenproject.org) smtp.mailfrom=xen-devel-bounces@lists.xenproject.org ARC-Seal: i=1; a=rsa-sha256; t=1569557992; cv=none; d=zoho.com; s=zohoarc; b=HmXlhFkBqk4bshh1Qr1804yxHKYf/uMJFlc78yu1CstbCpXhPlryMkucKWOPQeno2vSXOcf6SQR7yUMx3nrhzrCuZs1zwlSsSihqcQagZPVfY/vqXJIegg/fiiPByqYo/Oog+wNYL4rLCvC+OkP69LsBt96thIbt+K3K+XMtbn4= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zoho.com; s=zohoarc; t=1569557992; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To:ARC-Authentication-Results; bh=kUqUaqbyiOwCosLUazaBFfz/rmptL+vA23kpIL6x1Ok=; b=jjNGNFRX8ZbI3f06SlzVM75148Hhvd5JRTP22xB8zeJc0Iyb+Ne3E/rZBZC410ql1xwfjzf89kgxUgRDlHqfEaDKD8iL7F8eIix7hsg/3s5JqMURYHrRVjb2nkKXdnaDOT6tICMQwb2uzn7WoSTfWy2Ig/grfNebYHcuHC5d4BQ= ARC-Authentication-Results: i=1; mx.zoho.com; spf=none (zoho.com: 192.237.175.120 is neither permitted nor denied by domain of lists.xenproject.org) smtp.mailfrom=xen-devel-bounces@lists.xenproject.org Return-Path: Received: from lists.xenproject.org (lists.xenproject.org [192.237.175.120]) by mx.zohomail.com with SMTPS id 1569557992568915.9756975091381; Thu, 26 Sep 2019 21:19:52 -0700 (PDT) Received: from localhost ([127.0.0.1] helo=lists.xenproject.org) by lists.xenproject.org with esmtp (Exim 4.89) (envelope-from ) id 1iDhiP-0003F3-Jn; Fri, 27 Sep 2019 04:18:45 +0000 Received: from us1-rack-iad1.inumbo.com ([172.99.69.81]) by lists.xenproject.org with esmtp (Exim 4.89) (envelope-from ) id 1iDZdE-0001QW-8Y for xen-devel@lists.xenproject.org; Thu, 26 Sep 2019 19:40:52 +0000 Received: from mail.xenproject.org (unknown [104.130.215.37]) by localhost (Halon) with ESMTPS id 606c9456-e095-11e9-97fb-bc764e2007e4; Thu, 26 Sep 2019 19:39:38 +0000 (UTC) Received: from xenbits.xenproject.org ([104.239.192.120]) by mail.xenproject.org with esmtp (Exim 4.89) (envelope-from ) id 1iDZbx-0002Gj-GG; Thu, 26 Sep 2019 19:39:33 +0000 Received: from localhost ([127.0.0.1] helo=MacBook-Pro-2.Home) by xenbits.xenproject.org with esmtp (Exim 4.89) (envelope-from ) id 1iDZbx-0007uS-7e; Thu, 26 Sep 2019 19:39:33 +0000 X-Inumbo-ID: 606c9456-e095-11e9-97fb-bc764e2007e4 From: Lars Kurth To: xen-devel@lists.xenproject.org Date: Thu, 26 Sep 2019 20:39:22 +0100 Message-Id: <97e3adf75cf71ba39e702d4cab23236ada8d5a6c.1569525222.git.lars.kurth@citrix.com> X-Mailer: git-send-email 2.13.0 In-Reply-To: References: MIME-Version: 1.0 In-Reply-To: References: X-Mailman-Approved-At: Fri, 27 Sep 2019 04:18:43 +0000 Subject: [Xen-devel] [PATCH v2 4/6] Add Code Review Guide X-BeenThere: xen-devel@lists.xenproject.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: Xen developer discussion List-Unsubscribe: , List-Post: List-Help: List-Subscribe: , Cc: Lars Kurth , xen-api@lists.xenproject.org, minios-devel@lists.xenproject.org, committers@xenproject.org, mirageos-devel@lists.xenproject.org, win-pv-devel@lists.xenproject.org Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Errors-To: xen-devel-bounces@lists.xenproject.org Sender: "Xen-devel" From: Lars Kurth This document highlights what reviewers such as maintainers and committers = look for when reviewing code. It sets expectations for code authors and provides a framework for code reviewers. Signed-off-by: Lars Kurth --- Cc: minios-devel@lists.xenproject.org Cc: xen-api@lists.xenproject.org Cc: win-pv-devel@lists.xenproject.org Cc: mirageos-devel@lists.xenproject.org Cc: committers@xenproject.org --- code-review-guide.md | 125 +++++++++++++++++++++++++++++++++++++++++++++++= ++++ 1 file changed, 125 insertions(+) create mode 100644 code-review-guide.md diff --git a/code-review-guide.md b/code-review-guide.md new file mode 100644 index 0000000..8639431 --- /dev/null +++ b/code-review-guide.md @@ -0,0 +1,125 @@ +# Code Review Guide + +This document highlights what reviewers such as maintainers and committers= look +for when reviewing your code. It sets expectations for code authors and pr= ovides +a framework for code reviewers. + +This document does **not cover** the following topics: +* [Communication Best Practice](communication-practice.md) +* [Resolving Disagreement](resolving-disagreement.md) +* [Patch Submission Workflow](https://wiki.xenproject.org/wiki/Submitting_= Xen_Project_Patches) +* [Managing Patch Submission with Git](https://wiki.xenproject.org/wiki/Ma= naging_Xen_Patches_with_Git) + +## What we look for in Code Reviews +When performing a code review, reviewers typically look for the following = things + +### Is the change necessary to accomplish the goals? +* Is it clear what the goals are? +* Do we need to make a change, or can the goals be met with existing + functionality? + +### Architecture / Interface +* Is this the best way to solve the problem? +* Is this the right part of the code to modify? +* Is this the right level of abstraction? +* Is the interface general enough? Too general? Forward compatible? + +### Functionality +* Does it do what it=E2=80=99s trying to do? +* Is it doing it in the most ef=EF=AC=81cient way? +* Does it handle all the corner / error cases correctly? + +### Maintainability / Robustness +* Is the code clear? Appropriately commented? +* Does it duplicate another piece of code? +* Does the code make hidden assumptions? +* Does it introduce sections which need to be kept **in sync** with other = sections? +* Are there other **traps** someone modifying this code might fall into? + +**Note:** Sometimes you will work in areas which have identified maintaina= bility +and/or robustness issues. In such cases, maintainers may ask you to make a= dditional +changes, such that your submitted code does not make things worse or point= you +to other patches are already being worked on. + +### System properties +In some areas of the code, system properties such as +* Code size +* Performance +* Scalability +* Latency +* Complexity +* &c +are also important during code reviews. + +### Style +* Comments, carriage returns, **snuggly braces**, &c +* See [CODING_STYLE](https://xenbits.xenproject.org/gitweb/?p=3Dxen.git;a= =3Dblob;f=3DCODING_STYLE) + and [tools/libxl/CODING_STYLE](https://xenbits.xenproject.org/gitweb/?p= =3Dxen.git;a=3Dblob;f=3Dtools/libxl/CODING_STYLE) +* No extraneous whitespace changes + +### Documentation and testing +* If there is pre-existing documentation in the tree, such as man pages, d= esign + documents, etc. a contributor may be asked to update the documentation a= longside + the change. Documentation is typically present in the + [docs](https://xenbits.xen.org/gitweb/?p=3Dxen.git;a=3Dtree;f=3Ddocs) fo= lder. +* When adding new features that have an impact on the end-user, + a contributor should include an update to the + [SUPPORT.md](https://xenbits.xen.org/gitweb/?p=3Dxen.git;a=3Dtree;f=3Ddo= cs) file. + Typically, more complex features require several patch series before it = is ready to be + advertised in SUPPORT.md +* When adding new features, a contributor may be asked to provide tests or + ensure that existing tests pass + +#### Testing for the Xen Project Hypervisor +Tests are typically located in one of the following directories +* **Unit tests**: [tools/tests](https://xenbits.xenproject.org/gitweb/?p= =3Dxen.git;a=3Dtree;f=3Dtools/tests) +or [xen/test](https://xenbits.xenproject.org/gitweb/?p=3Dxen.git;a=3Dtree;= f=3Dxen/test)
+ Unit testing is hard for a system like Xen and typically requires buildi= ng a subsystem of + your tree. If your change can be easily unit tested, you should consider= submitting tests + with your patch. +* **Build and smoke test**: see [Xen GitLab CI](https://gitlab.com/xen-pro= ject/xen/pipelines)
+ Runs build tests for a combination of various distros and compilers agai= nst changes + committed to staging. Developers can join as members and test their deve= lopment + branches **before** submitting a patch. +* **XTF tests** (microkernel-based tests): see [XTF](https://xenbits.xenpr= oject.org/docs/xtf/)
+ XTF has been designed to test interactions between your software and har= dware. + It is a very useful tool for testing low level functionality and is exec= uted as part of the + project's CI system. XTF can be easily executed locally on xen.git trees. +* **osstest**: see [README](https://xenbits.xenproject.org/gitweb/?p=3Doss= test.git;a=3Dblob;f=3DREADME)
+ Osstest is the Xen Projects automated test system, which tests basic Xen= use cases on + a variety of different hardware. Before changes are committed, but **aft= er** they have + been reviewed. A contributor=E2=80=99s changes **cannot be applied to ma= ster** unless the + tests pass this test suite. Note that XTF and other tests are also execu= ted as part of + osstest. + +### Patch / Patch series information +* Informative one-line changelog +* Full changelog +* Motivation described +* All important technical changes mentioned +* Changes since previous revision listed +* Reviewed-by=E2=80=99s and Acked-by=E2=80=99s dropped if appropriate + +More information related to these items can be found in our +[Patch submission Guide](https://wiki.xenproject.org/wiki/Submitting_Xen_P= roject_Patches). + +## Reviewing for Patch Authors + +The following presentation by George Dunlap, provides an excellent overvie= w on how +we do code reviews, specifically targeting non-maintainers. + +As a community, we would love to have more help reviewing, including from = **new +community members**. But many people +* do not know where to start, or +* believe that their review would not contribute much, or +* may feel intimidated reviewing the code of more established community me= mbers + +The presentation demonstrates that you do not need to worry about any of t= hese +concerns. In addition, reviewing other people's patches helps you +* write better patches and experience the code review process from the oth= er side +* and build more influence within the community over time + +Thus, we recommend strongly that **patch authors** read the watch the reco= rding or +read the slides: +* [Patch Review for Non-Maintainers slides](https://www.slideshare.net/xen= _com_mgr/xpdds19-keynote-patch-review-for-nonmaintainers-george-dunlap-citr= ix-systems-uk-ltd) +* [Patch Review for Non-Maintainers recording - 20"](https://www.youtube.c= om/watch?v=3DehZvBmrLRwg) --=20 2.13.0 _______________________________________________ Xen-devel mailing list Xen-devel@lists.xenproject.org https://lists.xenproject.org/mailman/listinfo/xen-devel From nobody Wed May 1 10:44:54 2024 Delivered-To: importer@patchew.org Received-SPF: none (zoho.com: 192.237.175.120 is neither permitted nor denied by domain of lists.xenproject.org) client-ip=192.237.175.120; envelope-from=xen-devel-bounces@lists.xenproject.org; helo=lists.xenproject.org; Authentication-Results: mx.zohomail.com; spf=none (zoho.com: 192.237.175.120 is neither permitted nor denied by domain of lists.xenproject.org) smtp.mailfrom=xen-devel-bounces@lists.xenproject.org ARC-Seal: i=1; a=rsa-sha256; t=1569557994; cv=none; d=zoho.com; s=zohoarc; b=VO1pQzJA41GBxZawV7sTM+ykLg20pVFMJ9hJv5fnVq+m2aiz7vL1o9yR+G47xyXJOF9zCIxdIK/GBX/ZAuTzflHTg9WuWtvCjyijgCBSxeVMm9VGqAWphYoHDT17pTnDSQq8nrSpwkK2jme6YQHrVPaaY3WX9B/PqW2FzglKxME= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zoho.com; s=zohoarc; t=1569557994; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To:ARC-Authentication-Results; bh=EeAuKztUmcX1DT4K9kJ/ulwLAEBHA3UMwmWeiciDDew=; b=SfFb7m1vDnmaICfEPHFgJ4WJO+b5jH+Wxo9H9sci6Yp7dql/6lBTRST+dOKca5ItHbcUEkIWX4jiJUg9mPQmBQLW3J+yG7bPT+ysEgzBbWjIwhXxj7OdLXdco2YW0ZqX6wYmEytf7b9XecIxZO73+sf4Fx6RsUTrMV0RqgekSEo= ARC-Authentication-Results: i=1; mx.zoho.com; spf=none (zoho.com: 192.237.175.120 is neither permitted nor denied by domain of lists.xenproject.org) smtp.mailfrom=xen-devel-bounces@lists.xenproject.org Return-Path: Received: from lists.xenproject.org (lists.xenproject.org [192.237.175.120]) by mx.zohomail.com with SMTPS id 1569557994066457.0823434376372; Thu, 26 Sep 2019 21:19:54 -0700 (PDT) Received: from localhost ([127.0.0.1] helo=lists.xenproject.org) by lists.xenproject.org with esmtp (Exim 4.89) (envelope-from ) id 1iDhiQ-0003Fi-1R; Fri, 27 Sep 2019 04:18:46 +0000 Received: from us1-rack-iad1.inumbo.com ([172.99.69.81]) by lists.xenproject.org with esmtp (Exim 4.89) (envelope-from ) id 1iDZds-0001Vc-AZ for xen-devel@lists.xenproject.org; Thu, 26 Sep 2019 19:41:32 +0000 Received: from mail.xenproject.org (unknown [104.130.215.37]) by localhost (Halon) with ESMTPS id 61017954-e095-11e9-bf31-bc764e2007e4; Thu, 26 Sep 2019 19:39:39 +0000 (UTC) Received: from xenbits.xenproject.org ([104.239.192.120]) by mail.xenproject.org with esmtp (Exim 4.89) (envelope-from ) id 1iDZby-0002Gt-Ha; Thu, 26 Sep 2019 19:39:34 +0000 Received: from localhost ([127.0.0.1] helo=MacBook-Pro-2.Home) by xenbits.xenproject.org with esmtp (Exim 4.89) (envelope-from ) id 1iDZby-0007uS-8n; Thu, 26 Sep 2019 19:39:34 +0000 X-Inumbo-ID: 61017954-e095-11e9-bf31-bc764e2007e4 From: Lars Kurth To: xen-devel@lists.xenproject.org Date: Thu, 26 Sep 2019 20:39:23 +0100 Message-Id: <749f082bdb996ba7c7362847b22030882dc2903f.1569525222.git.lars.kurth@citrix.com> X-Mailer: git-send-email 2.13.0 In-Reply-To: References: MIME-Version: 1.0 In-Reply-To: References: X-Mailman-Approved-At: Fri, 27 Sep 2019 04:18:43 +0000 Subject: [Xen-devel] [PATCH v2 5/6] Add guide on Communication Best Practice X-BeenThere: xen-devel@lists.xenproject.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: Xen developer discussion List-Unsubscribe: , List-Post: List-Help: List-Subscribe: , Cc: Lars Kurth , xen-api@lists.xenproject.org, minios-devel@lists.xenproject.org, committers@xenproject.org, mirageos-devel@lists.xenproject.org, win-pv-devel@lists.xenproject.org Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Errors-To: xen-devel-bounces@lists.xenproject.org Sender: "Xen-devel" From: Lars Kurth This guide covers the bulk on Best Practice related to code review It primarily focusses on code review interactions It also covers how to deal with Misunderstandings and Cultural Differences Signed-off-by: Lars Kurth --- Cc: minios-devel@lists.xenproject.org Cc: xen-api@lists.xenproject.org Cc: win-pv-devel@lists.xenproject.org Cc: mirageos-devel@lists.xenproject.org Cc: committers@xenproject.org --- communication-practice.md | 410 ++++++++++++++++++++++++++++++++++++++++++= ++++ 1 file changed, 410 insertions(+) create mode 100644 communication-practice.md diff --git a/communication-practice.md b/communication-practice.md new file mode 100644 index 0000000..db9a5ef --- /dev/null +++ b/communication-practice.md @@ -0,0 +1,410 @@ +# Communication Best Practice + +This guide provides communication Best Practice that helps you in +* Using welcoming and inclusive language +* Keeping discussions technical and actionable +* Being respectful of differing viewpoints and experiences +* Being aware of your own and counterpart=E2=80=99s communication style an= d culture +* Show empathy towards other community members + +## Code reviews for **reviewers** and **patch authors** + +Before embarking on a code review, it is important to remember that +* A poorly executed code review can hurt the contributors feeling, even wh= en a reviewer + did not intend to do so. Feeling defensive is a normal reaction to a cri= tique or feedback. + A reviewer should be aware of how the pitch, tone, or sentiment of their= comments + could be interpreted by the contributor. The same applies to responses o= f an author + to the reviewer. +* When reviewing someone's code, you are ultimately looking for issues. A = good code + reviewer is able to mentally separate finding issues from articulating c= ode review + comments in a constructive and positive manner: depending on your person= ality this + can be **difficult** and you may need to develop a technique that works = for you. +* As software engineers we like to be proud of the solutions we came up wi= th. This can + make it easy to take another people=E2=80=99s criticism personally. Alwa= ys remember that it is + the code that is being reviewed, not you as a person. +* When you receive code review feedback, please be aware that we have revi= ewers + from different backgrounds, communication styles and cultures. Although = we all trying + to create a productive, welcoming and agile environment, we do not alway= s succeed. + +### Express appreciation +As the nature of code review to find bugs and possible issues, it is very = easy for +reviewers to get into a mode of operation where the patch review ends up b= eing a list +of issues, not mentioning what is right and well done. This can lead to th= e code +submitter interpreting your feedback in a negative way. + +The opening of a code review provides an opportunity to address this and a= lso sets the +tone for the rest of the code review. Starting **every** review on a posit= ive note, helps +set the tone for the rest of the review. + +For an initial patch, you can use phrases such as +> Thanks for the patch +> Thanks for doing this + +For further revisions within a review, phrases such as +> Thank you for addressing the last set of changes + +If you believe the code was good, it is good practice to highlight this by= using phrases +such as +> Looks good, just a few comments +> The changes you have made since the last version look good + +If you think there were issues too many with the code to use one of the ph= rases, +you can still start on a positive note, by for example saying +> I think this is a good change +> I think this is a good feature proposal + +It is also entirely fine to highlight specific changes as good. The best p= lace to +do this, is at top of a patch, as addressing code review comments typicall= y requires +a contributor to go through the list of things to address and an in-lined = positive +comment is likely to break that workflow. + +You should also consider, that if you review a patch of an experienced +contributor phrases such as *Thanks for the patch* could come across as +patronizing, while using *Thanks for doing this* is less likely to be inte= rpreted +as such. + +Appreciation should also be expressed by patch authors when asking for cla= rifications +to a review or responding to questions. A simple +> Thank you for your feedback +> Thank you for your reply +> Thank you XXX! + +is normally sufficient. + +### Avoid opinion: stick to the facts +The way how a reviewer expresses feedback, has a big impact on how the aut= hor +perceives the feedback. Key to this is what we call **stick to the facts**= . The same is +true when a patch author is responding to a comment from a reviewer. + +One of our maintainers has been studying Mandarin for several years and ha= s come +across the most strongly-worded dictionary entry +[he has ever seen](https://youtu.be/ehZvBmrLRwg?t=3D834). This example +illustrates the problem of using opinion in code reviews vs. using facts e= xtremely well. + +> =E8=A3=B9=E8=84=9A (guo3 jiao3): foot-binding (a vile feudal practice wh= ich crippled women both +> physically and spiritually) + +This is not something one is used to hearing from dictionary entries. Once= you +investigate the practice foot-binding, it is hard to disagree with the dic= tionart entry. +However, the statement does not contain much information. If you read it w= ithout +knowing what foot-binding is, it is hard to be convinced by this statement= . The main +take-away is that the author of the dictionary entry had strong opinions a= bout this topic. +It does not tell you, why you should have the same opinion. + +Compare this to the (Wikipedia entry)[https://en.wikipedia.org/wiki/Foot_b= inding] + +> Foot binding was the custom of applying tight binding to the feet of you= ng girls to +> modify the shape and size of their feet. ... foot binding was a painful = practice and +> significantly limited the mobility of women, resulting in lifelong disab= ilities for most of +> its subjects. ... Binding usually started during the winter months since= the feet were +> more likely to be numb, and therefore the pain would not be as extreme. = =E2=80=A6The toes on +> each foot were curled under, then pressed with great force downwards and= squeezed +> into the sole of the foot until the toes broke=E2=80=A6 + +Without going into the details of foot-binding, it is noticeable that none= of what is written +above uses opinion which could be interpreted as inflammatory language. It= is a list of +simple facts that are laid out in a way that make it obvious what the corr= ect conclusion +is. + +Because the Wikipedia entry is entirely fact based it is more powerful and= persuasive +then the dictionary entry. The same applies to code reviews. + +Making statements in code reviews such as +> Your code is garbage +> This idea is stupid + +besides being an opinion is rude and counter productive +* It will make the patch author angry: instead of finding a solution to th= e problem the + author will spend time and mental energy wrestling with their feelings +* It does not contain any information +* Facts are both more powerful and more persuasive + +Consider the following two pieces of feedback on a piece of code +> This piece of code is confusing +> It took me a long time to =EF=AC=81gure out what was going on here + +The first example expresses an opinion, whereas the second re-phrases the = statement +in terms of what you experienced, which is a fact. + +Other examples: +> BAD: This is fragile +> SOMEWHAT BETTER: This seems fragile to me +> BEST: If X happens, Y will happen. + +A certain piece of code can be written in many different ways: this can le= ad to +disagreements on the best architecture, design or coding pattern. As alrea= dy pointed out +in this section: avoid feedback that is opinion-based and thus does not ad= d any value. +Back your criticism (or idea on how to solve a problem) with a sensible ra= tionale. + +### Review the code, not the person +Without realizing it, it is easy to overlook the difference between insigh= tful critique of +code and personal criticism. Let's look at a theoretical function where th= ere is an +opportunity to return out of the function early. In this case, you could s= ay + +> You should return from this function early, because of XXX + +On its own, there is nothing wrong with this statement. However, a code re= view is made +up of multiple comments and using **You should** consistently can start to= feel negative +and can be mis-interpreted as a personal attack. Using something like avoi= ds this issue: + +> Returning from this function early is better, because of XXX + +Without personal reference, a code review will communicate the problem, id= ea or issue +without risking mis-interpretation. + +### Verbose vs. terse +Due to the time it takes to review and compose code reviewer, reviewers of= ten adopt a +terse style. It is not unusual to see review comments such as +> typo +> s/resions/regions/ +> coding style +> coding style: brackets not needed +etc. + +Terse code review style has its place and can be productive for both the r= eviewer and +the author. However, overuse can come across as unfriendly, lacking empath= y and +can thus create a negative impression with the author of a patch. This is = in particular +true, when you do not know the author or the author is a newcomer. Terse +communication styles can also be perceived as rude in some cultures. + +If you tend to use a terse commenting style and you do not know whether th= e author +is OK with it, it is often a good idea to compensate for it in the code re= view opening +(where you express appreciation) or when there is a need for verbose expre= ssion. + +It is also entirely fine to mention that you have a fairly terse communica= tion style +and ask whether the author is OK with it. In almost all cases, they will b= e: by asking +you are showing empathy that helps counteract a negative impression. + +### Code Review Comments should be actionable +Code review comments should be actionable: in other words, it needs to be = clear +what the author of the code needs to do to address the issue you identifie= d. + +Statements such as +> BAD: This is wrong +> BAD: This does not work +> BETTER, BUT NOT GOOD: This does not work, because of XXX + +do not normally provide the author of a patch with enough information to s= end out a +new patch version. By doing this, you essentially force the patch author t= o **find** and +**implement** an alternative, which then may also not be acceptable to you= as the +**reviewer** of the patch. + +A better way to approach this is to say + +> This does not work, because of XXX +> You may want to investigate YYY and ZZZ as alternatives + +In some cases, it may not be clear whether YYY or ZZZ are the better solut= ion. As a +reviewer you should be as up-front and possible in such a case and say som= ething like + +> I am not sure whether YYY and ZZZ are better, so you may want to outline= your +> thoughts about both solutions by e-mail first, such that we can decide w= hat works +> best + +### Identify the severity of an issue or disagreement +By default, every comment which is made **ought to be addressed** by the a= uthor. +However, often reviewers note issues, which would be nice if they were add= ressed, +but are not mandatory. + +Typically, reviewers use terminology such as +> This would be a nice-to-have +> This is not a blocker + +Some maintainers use +> NIT: XXX + +however, it is sometimes also used to indicate a minor issue that **must**= be fixed. + +During a code review, it can happen that reviewer and author disagree on h= ow to move +forward. The default position when it comes to disagreements is that **bot= h parties +want to argue their case**. However, frequently one or both parties do not= feel that +strongly about a specific issue. + +Within the Xen Project, we have [a way](https://xenproject.org/developers/= governance/#expressingopinion) +to highlight one's position on proposals, formal or informal votes using t= he following +notation: +> +2 : I am happy with this proposal, and I will argue for it +> +1 : I am happy with this proposal, but will not argue for it +> 0 : I have no opinion +> -1 : I am not happy with this proposal, but will not argue against it +> -2 : I am not happy with this proposal, and I will argue against it + +You can use a phrase such as +> I am not happy with this suggestion, but will not argue against it + +to make clear where you stand, while recording your position. Conversely, = a reviewer +may do something similar +> I am not happy with XYZ, but will not argue against it [anymore] +> What we have now is good enough, but could be better + +### Authors: responding to review comments +Typically patch authors are expected to **address all** review comments in= the next +version of a patch or patch series. In a smooth-running code review where = you do not +have further questions it is not at all necessary to acknowledge the chang= es you are +going to make: +* Simply send the next version with the changes addressed and record it in= the +change-log + +When there is discussion, the normal practice is to remove the portion of = the e-mail +thread where there is agreement. Otherwise, the thread can become exceptio= nally +long. + +In cases where there was discussion and maybe disagreement, it does howeve= r make +sense to close the discussion by saying something like + +> ACK +> Seems we are agreed, I am going to do this + +Other situations when you may want to do this are cases where the reviewer= made +optional suggestions, to make clear whether the suggestion will be followe= d or +not. + +### Avoid uncommon words: not everyone is a native English speaker +Avoid uncommon words both when reviewing code or responding to a review. N= ot +everyone is a native English speaker. The use of such words can come acros= s badly and +can lead to misunderstandings. + +### Prioritize significant flaws +If a patch or patch series has significant flaws, such as +* It is built on wrong assumptions +* There are issues with the architecture or the design + +it does not make sense to do a detailed code review. In such cases, it is = best to +focus on the major issues first and deal with style and minor issues in a = subsequent +review. This reduces the workload on both the reviewer and patch author. H= owever, +reviewers should make clear that they have omitted detailed review comment= s and +that these will come later. + +### Welcome newcomers +When reviewing the first few patches of a newcomer to the project, you may= want +spend additional time and effort in your code review. This contributes to = a more +**positive experience**, which ultimately helps create a positive working = relationship in +the long term. + +When someone does their first code submission, they will not be familiar w= ith **all** +conventions in the project. A good approach is to +* Welcome the newcomer +* Offer to help with specific questions, for example on IRC +* Point to existing documentation: in particular if mistakes with the subm= ission + itself were made. In most situations, following the submission process m= akes + the process more seamless for the contributor. So, you could say somethi= ng like + +> Hi XXX. Welcome to the community and thank you for the patch +> +> I noticed that the submission you made seems to not follow our process. +> Are you aware of this document at YYY? If you follow the instructions the +> entire code submission process and dealing with review comments becomes +> much easier. Feel free to find me on IRC if you need specific help. My I= RC +> handle is ZZZ + +### Review the code, then review the review +As stated earlier it is often difficult to mentally separate finding issue= s from articulating +code review comments in a constructive and positive manner. Even as an exp= erienced +code reviewer you can be in a bad mood, which can impact your communicatio= n style. + +A good trick to avoid this, is to start and complete the code review and t= hen **not +send it immediately**. You can then have a final go over the code review a= t some later +point in time and review your comments from the other author's point of vi= ew. This +minimizes the risk of being misunderstood. The same applies when replying = to a code +review: draft your reply and give it a final scan before pressing the send= button. + +Generally, it is a good idea for code reviewers to do this regularly, pure= ly from the +viewpoint of self-improvement and self-awareness. + +## Common Communication Pitfalls + +This section contains common communication issues and provides suggestions= on +how to avoid them and resolve them. These are **general** issues which aff= ect **all** +online communication. As such, we can only try and do our best. + +### Misunderstandings +When you meet face to face, you can read a person=E2=80=99s emotions. Even= with a phone call, +someone=E2=80=99s tone of voice can convey a lot of information. Using on-= line communication +channels you are flying blind, which often leads to misunderstandings. +[Research](https://www.wired.com/2006/02/the-secret-cause-of-flame-wars/) = shows +that in up to 50% of email conversations, the tone of voice is misinterpre= ted. + +In code reviews and technical discussions in general we tend to see two th= ings +* The reviewer or author interprets an exchange as too critical, passive a= ggressive, or +other: this usually comes down to different cultures and communication sty= les, which +are covered in the next section +* There is an actual misunderstanding of a subject under discussion + +In the latter case, the key to resolution is to **identify the misundersta= nding** as quickly +as possible and call it out and de-escalate rather than let the misunderst= anding linger. +This is inherently difficult and requires more care than normal communicat= ion. Typically +you would start with +* Showing appreciation +* Highlighting the potential misunderstanding and verifying whether the ot= her person + also feels that maybe there was a misunderstanding +* Proposing a way forward: for example, it may make sense to move the conv= ersation + from the mailing list to [IRC](https://xenproject.org/help/irc/) either = in private or public, + a community call or a private phone/video call. + +It is entirely acceptable to do this in a direct reply to your communicati= on partner, rather +than on a public e-mail list on or an otherwise public forum. + +A good approach is to use something like the following: +> Hi XXX! Thank you for the insights you have given me in this code review +> I feel that we are misunderstanding each other on the topic of YYY +> Would you mind trying to resolve this on IRC. I am available at ZZZ + +Usually, technical misunderstandings come down two either +1. Misinterpreting what the other person meant +2. Different - usually unstated - assumptions on how something works or wh= at is to be +achieved +3. Different - usually unstated - objectives and goals, which may be confl= icting +4. Real differences in opinion + +The goal of calling out a possible misunderstanding is to establish what c= aused the +misunderstanding, such that all parties can move forward. Typically, 1 and= 2 are easily +resolved and will lead back to a constructive discussion. Whereas 3 and 4 = may highlight +an inherent disagreement, which may need to be resolved through techniques= as +outlined in [Resolving Disagreement] (resolving-disagreement.md). + +### Cultural differences and different communication styles +The Xen Project is a global community with contributors from many different +backgrounds. Typically, when we communicate with a person we know, we fact= or +in past interactions. The less we know a person, the more we rely on cultu= ral norms. + +However, different norms and value systems come into play when people from= diverse +cultural backgrounds interact. That can lead to misunderstandings, especia= lly in +sensitive situations such as conflict resolution, giving and receiving fee= dback, and +consensus building. + +For example, giving direct feedback such as +> [Please] replace XXX with YYY, as XXX does not do ZZZ + +is acceptable and normal in some cultures, whereas in cultures which value= indirect +feedback it would be considered rude. In the latter case, something like t= he following +would be used +> This looks very good to me, but I believe you should use YYY here, +> because XXX would.... + +The key to working and communicating well with people from different cultu= ral +backgrounds is **self-awareness**, which can then be used to either +* Adapt your own communication style depending on who you talk to +* Or to find a middle-ground that covers most bases + +A number of different theories in the field of working effectively are cur= rently popular, +with the most well-known one being +[Erin Meyer's Culture Map](https://en.wikipedia.org/wiki/Erin_Meyer). A sh= ort overview +can be found +[here](https://www.nsf.gov/attachments/134059/public/15LFW_WorkingWithMult= iculturalTeams_LarsonC.pdf) +[33 slides]. + +### Code reviews and discussions are not competitions +Code reviews on our mailing lists are not competitions on who can come up = with the +smartest solution or who is the real coding genius. + +In a code review - as well as in general - we expect that all stake-holders +* Gracefully accept constructive criticism +* Focus on what is best for the community +* Resolve differences in opinion effectively + +The next section provides pointers on how to do this effectively. + +### Resolving Disagreement Effectively +Common scenarios are covered our guide on +[Resolving Disagreement](resolving-disagreement.md), which lays out situat= ions that +can lead to dead-lock and shows common patterns on how to avoid and resolv= e issues. --=20 2.13.0 _______________________________________________ Xen-devel mailing list Xen-devel@lists.xenproject.org https://lists.xenproject.org/mailman/listinfo/xen-devel From nobody Wed May 1 10:44:54 2024 Delivered-To: importer@patchew.org Received-SPF: none (zoho.com: 192.237.175.120 is neither permitted nor denied by domain of lists.xenproject.org) client-ip=192.237.175.120; envelope-from=xen-devel-bounces@lists.xenproject.org; helo=lists.xenproject.org; Authentication-Results: mx.zohomail.com; spf=none (zoho.com: 192.237.175.120 is neither permitted nor denied by domain of lists.xenproject.org) smtp.mailfrom=xen-devel-bounces@lists.xenproject.org ARC-Seal: i=1; a=rsa-sha256; t=1569557992; cv=none; d=zoho.com; s=zohoarc; b=MU5lhK19gb8S+LKnLL0pqKd7kJckGA2kuWbsIjby0L3+Hwu6hPPTECpYh1L58vvI8ERl2Ws2o5UcU+YsECRKPm3eHxa0vnjcpZvBPhQ5dCMGS0t5PUAMKGZQtw+HsJNVepY5+112FyIZQtjUFU+NUArVUJNZv4eYQ8OX9HfTdhs= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zoho.com; s=zohoarc; t=1569557992; h=Content-Type:Content-Transfer-Encoding:Cc:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To:ARC-Authentication-Results; bh=9SUg41pKZetdp+daVguL4OwSEXiocKJK9xzBAEvABqI=; b=ZjgxsY0e9SK5mxGl7zB0M/x9RyJv02w58R+30F1Dkp0hrtCZsN7w3qRqRXw6zhamI3JoUGCfNQuVlo9ln44gmZxWbMmeI9dbMBjiOclonK32at8ja4+1ulQ6gdPsYVI6j3Yn7DEMGkvgXAXZUgzdsTkxJJfu0w1Z6Iv0T0sw3ac= ARC-Authentication-Results: i=1; mx.zoho.com; spf=none (zoho.com: 192.237.175.120 is neither permitted nor denied by domain of lists.xenproject.org) smtp.mailfrom=xen-devel-bounces@lists.xenproject.org Return-Path: Received: from lists.xenproject.org (lists.xenproject.org [192.237.175.120]) by mx.zohomail.com with SMTPS id 1569557992334983.7653442531722; Thu, 26 Sep 2019 21:19:52 -0700 (PDT) Received: from localhost ([127.0.0.1] helo=lists.xenproject.org) by lists.xenproject.org with esmtp (Exim 4.89) (envelope-from ) id 1iDhiO-0003E6-V1; Fri, 27 Sep 2019 04:18:44 +0000 Received: from all-amaz-eas1.inumbo.com ([34.197.232.57] helo=us1-amaz-eas2.inumbo.com) by lists.xenproject.org with esmtp (Exim 4.89) (envelope-from ) id 1iDZcj-0001N6-My for xen-devel@lists.xenproject.org; Thu, 26 Sep 2019 19:40:21 +0000 Received: from mail.xenproject.org (unknown [104.130.215.37]) by localhost (Halon) with ESMTPS id 624bdf52-e095-11e9-965e-12813bfff9fa; Thu, 26 Sep 2019 19:39:41 +0000 (UTC) Received: from xenbits.xenproject.org ([104.239.192.120]) by mail.xenproject.org with esmtp (Exim 4.89) (envelope-from ) id 1iDZbz-0002H2-GV; Thu, 26 Sep 2019 19:39:35 +0000 Received: from localhost ([127.0.0.1] helo=MacBook-Pro-2.Home) by xenbits.xenproject.org with esmtp (Exim 4.89) (envelope-from ) id 1iDZbz-0007uS-Ac; Thu, 26 Sep 2019 19:39:35 +0000 X-Inumbo-ID: 624bdf52-e095-11e9-965e-12813bfff9fa From: Lars Kurth To: xen-devel@lists.xenproject.org Date: Thu, 26 Sep 2019 20:39:24 +0100 Message-Id: <2e4b36afaa73277d246d7e84037db1532a136ec7.1569525222.git.lars.kurth@citrix.com> X-Mailer: git-send-email 2.13.0 In-Reply-To: References: In-Reply-To: References: X-Mailman-Approved-At: Fri, 27 Sep 2019 04:18:43 +0000 Subject: [Xen-devel] [PATCH v2 6/6] Added Resolving Disagreement X-BeenThere: xen-devel@lists.xenproject.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: Xen developer discussion List-Unsubscribe: , List-Post: List-Help: List-Subscribe: , Cc: Lars Kurth , xen-api@lists.xenproject.org, minios-devel@lists.xenproject.org, committers@xenproject.org, mirageos-devel@lists.xenproject.org, win-pv-devel@lists.xenproject.org MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Errors-To: xen-devel-bounces@lists.xenproject.org Sender: "Xen-devel" From: Lars Kurth This guide provides Best Practice on identifying and resolving common classes of disagreement Signed-off-by: Lars Kurth -- Cc: minios-devel@lists.xenproject.org Cc: xen-api@lists.xenproject.org Cc: win-pv-devel@lists.xenproject.org Cc: mirageos-devel@lists.xenproject.org Cc: committers@xenproject.org --- resolving-disagreement.md | 146 ++++++++++++++++++++++++++++++++++++++++++= ++++ 1 file changed, 146 insertions(+) create mode 100644 resolving-disagreement.md diff --git a/resolving-disagreement.md b/resolving-disagreement.md new file mode 100644 index 0000000..19aedbe --- /dev/null +++ b/resolving-disagreement.md @@ -0,0 +1,146 @@ +# Resolving Disagreement + +This guide provides Best Practice on resolving disagreement, such as +* Gracefully accept constructive criticism +* Focus on what is best for the community +* Resolve differences in opinion effectively + +## Theory: Paul Graham's hierarchy of disagreement +Paul Graham proposed a **disagreement hierarchy** in a 2008 essay=20 +**[How to Disagree](http://www.paulgraham.com/disagree.html)**, putting ty= pes of +arguments into a seven-point hierarchy and observing that *moving up the +disagreement hierarchy makes people less mean, and will make most of them = happier*. +Graham also suggested that the hierarchy can be thought of as a pyramid, a= s the=20 +highest forms of disagreement are rarer. + +| ![Graham's Hierarchy of Disagreemen](https://upload.wikimedia.org/wikipe= dia/commons/a/a3/Graham%27s_Hierarchy_of_Disagreement-en.svg) | +| *A representation of Graham's hierarchy of disagreement from [Loudacris]= (http://www.createdebate.com/user/viewprofile/Loudacris) modified by [Rocke= t000](https://en.wikipedia.org/wiki/User:Rocket000)* | + +In the context of the Xen Project we strive to **only use the top half** o= f the hierarchy. +**Name-calling** and **Ad hominem** arguments are not acceptable within th= e Xen +Project. + +## Issue: Scope creep + +One thing which occasionally happens during code review is that a code rev= iewer +asks or appears to ask the author of patch to implement additional functio= nality. + +This could take for example the form of +> Do you think it would be useful for the code to do XXX?=20 +> I can imagine a user wanting to do YYY (and XXX would enable this) + +That potentially adds additional work for the code author, which they may = not have +the time to perform. It is good practice for authors to consider such a re= quest in terms of +* Usefulness to the user +* Code churn, complexity or impact on other system properties +* Extra time to implement and report back to the reviewer + +If you believe that the impact/cost is too high, report back to the review= er. To resolve +this, it is advisable to +* Report your findings +* And then check whether this was merely an interesting suggestion, or som= ething the +reviewer feels more strongly about + +In the latter case, there are typically several common outcomes +* The **author and reviewer agree** that the suggestion should be implemen= ted +* The **author and reviewer agree** that it may make sense to defer implem= entation +* The **author and reviewer agree** that it makes no sense to implement th= e suggestion + +The author of a patch would typically suggest their preferred outcome, for= example +> I am not sure it is worth to implement XXX +> Do you think this could be done as a separate patch in future? + +In cases, where no agreement can be found, the best approach would be to g= et an +independent opinion from another maintainer or the project's leadership te= am. + +## Issue: [Bikeshedding](https://en.wiktionary.org/wiki/bikeshedding) + +Occasionally discussions about unimportant but easy-to-grasp issues can le= ad to +prolonged and unproductive discussion. The best way to approach this is to +try and **anticipate** bikeshedding and highlight it as such upfront. Howe= ver, the +format of a code review does not always lend itself well to this approach,= except +for highlighting it in the cover letter of a patch series. + +However, typically Bikeshedding issues are fairly easy to recognize in a c= ode review, +as you will very quickly get different reviewers providing differing opini= ons. In this case +it is best for the author or a reviewer to call out the potential bikeshed= ding issue using +something like + +> Looks we have a bikeshedding issue here +> I think we should call a quick vote to settle the issue + +Our governance provides the mechanisms of [informal votes](https://xenproj= ect.org/developers/governance/#informal-votes-or-surveys) or +[lazy voting](https://xenproject.org/developers/governance/#lazyconsensus)= which lend +themselves well to resolve such issues. + +## Issue: Small functional issues + +The most common area of disagreements which happen in code reviews, are di= ffering +opinions on whether small functional issues in a patch series have to be r= esolved or +not before the code is ready to be submitted. Such disagreements are typic= ally caused +by different expectations related to the level of perfection a patch serie= s needs to fulfil +before it can be considered ready to be committed. + +To explain this better, I am going to use the analogy of some building wor= k that has +been performed at your house. Let's say that you have a new bathroom insta= lled. +Before paying your builder the last instalment, you perform an inspection = and you find +issues such as +* The seals around the bathtub are not perfectly event +* When you open the tap, the plumbing initially makes some loud noise +* The shower mixer has been installed the wrong way around + +In all these cases, the bathroom is perfectly functional, but not perfect.= At this point +you have the choice to try and get all the issues addressed, which in the = example of +the shower mixer may require significant re-work and potentially push-back= from your +builder. You may have to refer to the initial statement of work, but it tu= rns out it does +not contain sufficient information to ascertain whether your builder had c= ommitted to +the level of quality you were expecting. + +Similar situations happen in code reviews very frequently and can lead to = a long +discussion before it can be resolved. The most important thing is to **ide= ntify** +a disagreement as such early and then call it out. Tips on how to do this,= can be found +[here](communication-practice.md#Misunderstandings). + +At this point, you will understand why you have the disagreement, but not = necessarily +agreement on how to move forward. An easy fix would be to agree to submit = the change +as it is and fix it in future. In a corporate software engineering environ= ment this is the +most likely outcome, but in open source communities additional concerns ha= ve to be +considered. +* Code reviewers frequently have been in this situation before with the mo= st common + outcome that the issue is then never fixed. By accepting the change, the= reviewers + have no leverage to fix the issue and may have to spend effort fixing th= e issue + themselves in future as it may impact the product they built on top of t= he code. +* Conversely, a reviewer may be asking the author to make too many changes= of this + type which ultimately may lead the author to not contribute to the proje= ct again. +* An author, which consistently does not address **any** of these issues m= ay end up + getting a bad reputation and may find future code reviews more difficult. +* An author which always addresses **all** of these issues may end up gett= ing into + difficulties with their employer, as they are too slow getting code upst= reamed. + +None of these outcomes are good, so ultimately a balance has been found. A= t the end +of the day, the solution should focus on what is best for the community, w= hich may +mean asking for an independent opinion as outlined in the next section. + +## Resolution: Asking for an independent opinion + +Most disagreements can be settled by +* Asking another maintainer or committer to provide an independent opinion= on the + specific issue in public to help resolve it +* Failing this an issue can be escalated to the project leadership team, w= hich is + expected to act as referee and make a decision on behalf of the community + +If you feel uncomfortable with this approach, you may also contact +mediation@xenproject.org to get advice. See our [Communication Guide](comm= unication-guide.md) +for more information. + +## Decision making and conflict resolution in our governance + +Our [governance](https://xenproject.org/developers/governance/#decisions) = contains +several proven mechanisms to help with decision making and conflict resolu= tion. + +See +* [Expressing agreement and disagreement](https://xenproject.org/developer= s/governance/#expressingopinion) +* [Lazy consensus / Lazy voting](https://xenproject.org/developers/governa= nce/#lazyconsensus) +* [Informal votes or surveys](https://xenproject.org/developers/governance= /#informal-votes-or-surveys) +* [Leadership team decisions](https://xenproject.org/developers/governance= /#leadership) +* [Conflict resolution](https://xenproject.org/developers/governance/#conf= lict) --=20 2.13.0 _______________________________________________ Xen-devel mailing list Xen-devel@lists.xenproject.org https://lists.xenproject.org/mailman/listinfo/xen-devel