From patchwork Fri Sep 11 12:40:02 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: George Dunlap X-Patchwork-Id: 11770449 Return-Path: Received: from mail.kernel.org (pdx-korg-mail-1.web.codeaurora.org [172.30.200.123]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id A3B57618 for ; Fri, 11 Sep 2020 12:41:25 +0000 (UTC) Received: from lists.xenproject.org (lists.xenproject.org [192.237.175.120]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id 703B322204 for ; Fri, 11 Sep 2020 12:41:25 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=fail reason="signature verification failed" (1024-bit key) header.d=citrix.com header.i=@citrix.com header.b="c5V9nSMZ" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 703B322204 Authentication-Results: mail.kernel.org; dmarc=fail (p=reject dis=none) header.from=citrix.com Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=xen-devel-bounces@lists.xenproject.org Received: from localhost ([127.0.0.1] helo=lists.xenproject.org) by lists.xenproject.org with esmtp (Exim 4.92) (envelope-from ) id 1kGiM6-0006iR-3y; Fri, 11 Sep 2020 12:40:42 +0000 Received: from us1-rack-iad1.inumbo.com ([172.99.69.81]) by lists.xenproject.org with esmtp (Exim 4.92) (envelope-from ) id 1kGiM5-0006hW-1j for xen-devel@lists.xenproject.org; Fri, 11 Sep 2020 12:40:41 +0000 X-Inumbo-ID: fc1f6b95-e160-48c0-b8b1-071ee2d75ff6 Received: from esa6.hc3370-68.iphmx.com (unknown [216.71.155.175]) by us1-rack-iad1.inumbo.com (Halon) with ESMTPS id fc1f6b95-e160-48c0-b8b1-071ee2d75ff6; Fri, 11 Sep 2020 12:40:39 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=simple/simple; d=citrix.com; s=securemail; t=1599828039; h=from:to:cc:subject:date:message-id:in-reply-to: references:mime-version:content-transfer-encoding; bh=Q1aCTFoFO9abujLiq4ebibIbZx1ARS5BNFG2U++NH3w=; b=c5V9nSMZ9RfhuaejLzuaaW2CeUKfAMNabtyTQO7aSSATkXWTxKXYwPbK Ym8Y5Dbvrmm3vtW8pSCMcOO4EQf5zpkyGbwOiqssou+Y18iPDhbuPsLeU dSUMatIArefqSor2QIEiQX2BUZTd+WpEVX8tEI0b/1M7HUOckTQg+zk3e Y=; Authentication-Results: esa6.hc3370-68.iphmx.com; dkim=none (message not signed) header.i=none IronPort-SDR: RL1PNVOr2asCZbkylcYaoSdjJfV1KmvBJTFx28YXKL5zYmWum4OzgYD8uwHMbfQQP+uQ0Xxukx es2OdgNh9Hsm5obHOM7S/asKHlUW+XgSOT2A28RG3xpR6T/UCmikpiNKGqhiJshjbITgA7axZ0 wz52mxPfRHhF3MV18cs3L/q5g/N8EH0qXaffj2qSfHXknZvfbzilM1x+8YOYS7V+rrWPVjZcbZ xynN8FeLEjvTZpq+/oMVUnGkp1ikIKDXdnax3165Ooj6G9yFVCTFcNSS0AahdJ1z/LI+Gdgl41 fg4= X-SBRS: 2.7 X-MesageID: 26789698 X-Ironport-Server: esa6.hc3370-68.iphmx.com X-Remote-IP: 162.221.158.21 X-Policy: $RELAYED X-IronPort-AV: E=Sophos;i="5.76,415,1592884800"; d="scan'208";a="26789698" From: George Dunlap To: CC: George Dunlap Subject: [PATCH 1/8] Add basic sphinx structure Date: Fri, 11 Sep 2020 13:40:02 +0100 Message-ID: <20200911124009.3760032-2-george.dunlap@citrix.com> X-Mailer: git-send-email 2.25.1 In-Reply-To: <20200911124009.3760032-1-george.dunlap@citrix.com> References: <20200911124009.3760032-1-george.dunlap@citrix.com> MIME-Version: 1.0 X-BeenThere: xen-devel@lists.xenproject.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Xen developer discussion List-Unsubscribe: , List-Post: List-Help: List-Subscribe: , Errors-To: xen-devel-bounces@lists.xenproject.org Sender: "Xen-devel" --- Makefile | 20 +++++++++++++++++++ source/conf.py | 52 ++++++++++++++++++++++++++++++++++++++++++++++++ source/index.rst | 20 +++++++++++++++++++ 3 files changed, 92 insertions(+) create mode 100644 Makefile create mode 100644 source/conf.py create mode 100644 source/index.rst diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..d0c3cbf --- /dev/null +++ b/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/source/conf.py b/source/conf.py new file mode 100644 index 0000000..7b99910 --- /dev/null +++ b/source/conf.py @@ -0,0 +1,52 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + + +# -- Project information ----------------------------------------------------- + +project = 'XenProject Governance' +copyright = '2020, The XenProject Team' +author = 'The XenProject Team' + + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = [] + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'alabaster' + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] \ No newline at end of file diff --git a/source/index.rst b/source/index.rst new file mode 100644 index 0000000..63f76f0 --- /dev/null +++ b/source/index.rst @@ -0,0 +1,20 @@ +.. XenProject Governance documentation master file, created by + sphinx-quickstart on Tue Sep 8 12:10:02 2020. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to XenProject Governance's documentation! +================================================= + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` From patchwork Fri Sep 11 12:40:03 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: George Dunlap X-Patchwork-Id: 11770455 Return-Path: Received: from mail.kernel.org (pdx-korg-mail-1.web.codeaurora.org [172.30.200.123]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 0CDE4618 for ; Fri, 11 Sep 2020 12:41:42 +0000 (UTC) Received: from lists.xenproject.org (lists.xenproject.org [192.237.175.120]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id CD774221F1 for ; Fri, 11 Sep 2020 12:41:41 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=fail reason="signature verification failed" (1024-bit key) header.d=citrix.com header.i=@citrix.com header.b="N19UTtrj" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org CD774221F1 Authentication-Results: mail.kernel.org; dmarc=fail (p=reject dis=none) header.from=citrix.com Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=xen-devel-bounces@lists.xenproject.org Received: from localhost ([127.0.0.1] helo=lists.xenproject.org) by lists.xenproject.org with esmtp (Exim 4.92) (envelope-from ) id 1kGiM7-0006jN-Dp; Fri, 11 Sep 2020 12:40:43 +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.92) (envelope-from ) id 1kGiM6-0006gu-EI for xen-devel@lists.xenproject.org; Fri, 11 Sep 2020 12:40:42 +0000 X-Inumbo-ID: 5bcef08e-e4f2-46ab-8753-7d71eb5f71d1 Received: from esa3.hc3370-68.iphmx.com (unknown [216.71.145.155]) by us1-amaz-eas2.inumbo.com (Halon) with ESMTPS id 5bcef08e-e4f2-46ab-8753-7d71eb5f71d1; Fri, 11 Sep 2020 12:40:39 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=simple/simple; d=citrix.com; s=securemail; t=1599828040; h=from:to:cc:subject:date:message-id:in-reply-to: references:mime-version:content-transfer-encoding; bh=F/qlRhZFUxwGusOfRvbWddJnOBDBsp3E2p6n6Sk+5gg=; b=N19UTtrji+LSW1kzBTdg/S+Y8jh/wjLrrQWKBsEWEBg40GvAzDqyjFNX HAm8Sg8lkE0h6X1sfwGP9Dn09oOzh6/8BwjzQ4uOrEyTgRljKJw0hUyvV qHTEOFty7MAd/6PwYy9ZikiAf54En1uKyizacH0ySrglVEr5huo39vGn0 U=; Authentication-Results: esa3.hc3370-68.iphmx.com; dkim=none (message not signed) header.i=none IronPort-SDR: RmZvlCYHFIMYpqyj7isFeaEcT/l0zKHOJrPWDi0XxF2JE3LZnzmpuM/aXbJT0ttb8bb5mj5Bq3 t09BmAIJytxXG5x7k2GegEvrIGZ5JYdcMjLTBhuRpEO+XKbpEQKGEUetxMJ/HCdSr2lv1CXtmF REKn4722Rk9TGtb7WqMGbD0dsIF2enFqogZkB9wBg4oUQjaIfnvE3oOkARkKEz1CJKTJuEim1n K5utrIOSP/wjgYuYweHieCptMp7/WZqwk7bzm9jtF0sMMbAL9RnkCDyo+h61VieqDyk6QjbLCK etA= X-SBRS: 2.7 X-MesageID: 26476154 X-Ironport-Server: esa3.hc3370-68.iphmx.com X-Remote-IP: 162.221.158.21 X-Policy: $RELAYED X-IronPort-AV: E=Sophos;i="5.76,415,1592884800"; d="scan'208";a="26476154" From: George Dunlap To: CC: George Dunlap Subject: [PATCH 2/8] Move docs into source directory, rename to rst Date: Fri, 11 Sep 2020 13:40:03 +0100 Message-ID: <20200911124009.3760032-3-george.dunlap@citrix.com> X-Mailer: git-send-email 2.25.1 In-Reply-To: <20200911124009.3760032-1-george.dunlap@citrix.com> References: <20200911124009.3760032-1-george.dunlap@citrix.com> MIME-Version: 1.0 X-BeenThere: xen-devel@lists.xenproject.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Xen developer discussion List-Unsubscribe: , List-Post: List-Help: List-Subscribe: , Errors-To: xen-devel-bounces@lists.xenproject.org Sender: "Xen-devel" --- code-of-conduct.md => source/code-of-conduct.md | 0 code-review-guide.md => source/code-review-guide.md | 0 communication-guide.md => source/communication-guide.md | 0 communication-practice.md => source/communication-practice.md | 0 source/index.rst | 1 - resolving-disagreement.md => source/resolving-disagreement.md | 0 6 files changed, 1 deletion(-) rename code-of-conduct.md => source/code-of-conduct.md (100%) rename code-review-guide.md => source/code-review-guide.md (100%) rename communication-guide.md => source/communication-guide.md (100%) rename communication-practice.md => source/communication-practice.md (100%) rename resolving-disagreement.md => source/resolving-disagreement.md (100%) diff --git a/code-of-conduct.md b/source/code-of-conduct.md similarity index 100% rename from code-of-conduct.md rename to source/code-of-conduct.md diff --git a/code-review-guide.md b/source/code-review-guide.md similarity index 100% rename from code-review-guide.md rename to source/code-review-guide.md diff --git a/communication-guide.md b/source/communication-guide.md similarity index 100% rename from communication-guide.md rename to source/communication-guide.md diff --git a/communication-practice.md b/source/communication-practice.md similarity index 100% rename from communication-practice.md rename to source/communication-practice.md diff --git a/source/index.rst b/source/index.rst index 63f76f0..99cb386 100644 --- a/source/index.rst +++ b/source/index.rst @@ -11,7 +11,6 @@ Welcome to XenProject Governance's documentation! :caption: Contents: - Indices and tables ================== diff --git a/resolving-disagreement.md b/source/resolving-disagreement.md similarity index 100% rename from resolving-disagreement.md rename to source/resolving-disagreement.md From patchwork Fri Sep 11 12:40:04 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: George Dunlap X-Patchwork-Id: 11770451 Return-Path: Received: from mail.kernel.org (pdx-korg-mail-1.web.codeaurora.org [172.30.200.123]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id AA0E592C for ; Fri, 11 Sep 2020 12:41:32 +0000 (UTC) Received: from lists.xenproject.org (lists.xenproject.org [192.237.175.120]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id 74999206DB for ; Fri, 11 Sep 2020 12:41:32 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=fail reason="signature verification failed" (1024-bit key) header.d=citrix.com header.i=@citrix.com header.b="ATBOOC6z" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 74999206DB Authentication-Results: mail.kernel.org; dmarc=fail (p=reject dis=none) header.from=citrix.com Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=xen-devel-bounces@lists.xenproject.org Received: from localhost ([127.0.0.1] helo=lists.xenproject.org) by lists.xenproject.org with esmtp (Exim 4.92) (envelope-from ) id 1kGiM5-0006i3-Qp; Fri, 11 Sep 2020 12:40:41 +0000 Received: from us1-rack-iad1.inumbo.com ([172.99.69.81]) by lists.xenproject.org with esmtp (Exim 4.92) (envelope-from ) id 1kGiM3-0006hW-Oh for xen-devel@lists.xenproject.org; Fri, 11 Sep 2020 12:40:39 +0000 X-Inumbo-ID: 12abceb6-0e6e-4b53-ac42-e0f20e5d1a1d Received: from esa6.hc3370-68.iphmx.com (unknown [216.71.155.175]) by us1-rack-iad1.inumbo.com (Halon) with ESMTPS id 12abceb6-0e6e-4b53-ac42-e0f20e5d1a1d; Fri, 11 Sep 2020 12:40:38 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=simple/simple; d=citrix.com; s=securemail; t=1599828038; h=from:to:cc:subject:date:message-id:in-reply-to: references:mime-version:content-transfer-encoding; bh=RIW8Kp6bukJ8jfRLiJqZntK27guAQKQDcsKbEPOP7X4=; b=ATBOOC6zo5XO0en1fJo6hX3MzfD+iYJUpJAG+hY1Db+27RLcE4a5Yl9g N88TeCXrx9ef6jJmJIfAfYzSNdsQzkn+x0FuJ/RxlRoNmZJNwlMnJYTKL Ubl+HTRTO2SHV5qrGG2KmPBiqaADRf/fvUBvZ6bbIJ2l0WvnbbZupBhDG o=; Authentication-Results: esa6.hc3370-68.iphmx.com; dkim=none (message not signed) header.i=none IronPort-SDR: GusAqBLP2hOZp55ijHdwqeBCR6JkxGGBvdGz4GE9Q2NbNgQQHFiVy+Sllo9C1SGV3lUkQfIvtd tN7snmpk2ZLmfERCBg6ovz+7cFxm46U9KLnrbH7A2c79FnUgLFLqwlYAx+ZNEB/95kp/GtGEtg QT5YpsjHAyYVadV9PmHyPhIoq3fYA+TU8UYxVNSgFw1RRUfkryba6RwpuGe2pAHICKsr99YNMN AKZjF745d960coYYEXd4XfpXePSxc4gkdXV7le8V38pFgFn0u81lhhYERxcbeCzxnBLEE9a3Dv ApM= X-SBRS: 2.7 X-MesageID: 26789697 X-Ironport-Server: esa6.hc3370-68.iphmx.com X-Remote-IP: 162.221.158.21 X-Policy: $RELAYED X-IronPort-AV: E=Sophos;i="5.76,415,1592884800"; d="scan'208";a="26789697" From: George Dunlap To: CC: George Dunlap Subject: [PATCH 3/8] Convert code-of-conduct to rst Date: Fri, 11 Sep 2020 13:40:04 +0100 Message-ID: <20200911124009.3760032-4-george.dunlap@citrix.com> X-Mailer: git-send-email 2.25.1 In-Reply-To: <20200911124009.3760032-1-george.dunlap@citrix.com> References: <20200911124009.3760032-1-george.dunlap@citrix.com> MIME-Version: 1.0 X-BeenThere: xen-devel@lists.xenproject.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Xen developer discussion List-Unsubscribe: , List-Post: List-Help: List-Subscribe: , Errors-To: xen-devel-bounces@lists.xenproject.org Sender: "Xen-devel" Underline section titles. Convert links to RST-style links. NB that the Communication Guide link won't work ATM; this will be fixed when we convert that document to RST. Adjust the formatting for the list so that it's converted properly. A couple of clean-ups: * Expand the label for communication guidance, and convert the link to the project governance to a named reference rather than an "embedded" URI. * Move all hyperlink targets to the bottom of the article, and put them in the order they're linked. No changes to the text. Signed-off-by: George Dunlap --- ...code-of-conduct.md => code-of-conduct.rst} | 39 ++++++++++++------- source/conf.py | 2 +- source/index.rst | 1 + 3 files changed, 27 insertions(+), 15 deletions(-) rename source/{code-of-conduct.md => code-of-conduct.rst} (83%) diff --git a/source/code-of-conduct.md b/source/code-of-conduct.rst similarity index 83% rename from source/code-of-conduct.md rename to source/code-of-conduct.rst index a6080cd..81efe04 100644 --- a/source/code-of-conduct.md +++ b/source/code-of-conduct.rst @@ -1,6 +1,8 @@ -# Xen Project Code of Conduct +Xen Project Code of Conduct +*************************** -## Our Pledge +Our Pledge +========== In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to make participation in our project and @@ -9,12 +11,13 @@ size, disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation. -## Our Standards +Our Standards +============= We believe that a Code of Conduct can help create a harassment-free environment, but is not sufficient to create a welcoming environment on its own: guidance on creating a welcoming environment, how to communicate in an effective and -friendly way, etc. can be found [here][guidance]]. +friendly way, etc. can be found `here `_. Examples of unacceptable behavior by participants include: @@ -27,7 +30,8 @@ Examples of unacceptable behavior by participants include: * Other conduct which could reasonably be considered inappropriate in a professional setting -## Our Responsibilities +Our Responsibilities +==================== Project leadership team members are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective @@ -39,7 +43,8 @@ contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful. -## Scope +Scope +===== 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 @@ -49,7 +54,8 @@ media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by the project leadership. -## What to do if you witness or are subject to unacceptable behavior +What to do if you witness or are subject to unacceptable behavior +================================================================= Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting Conduct Team members at conduct@xenproject.org. All @@ -67,25 +73,30 @@ Project leadership team members who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership. -## Conduct Team members +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 outlined -[here]: https://xenproject.org/developers/governance/#project-decisions +`here `_. -## Attribution +Attribution +=========== -This Code of Conduct is adapted from the [Contributor Covenant][homepage], +This Code of Conduct is adapted from the `Contributor Covenant`_, version 1.4, available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html -[homepage]: https://www.contributor-covenant.org -[guidance]: communication-guide.md - For answers to common questions about this code of conduct, see https://www.contributor-covenant.org/faq + +.. _Communication Guidance: communication-guide.md +.. _Project Governance: https://xenproject.org/developers/governance/#project-decisions +.. _Contributor Covenant: https://www.contributor-covenant.org diff --git a/source/conf.py b/source/conf.py index 7b99910..85bcedb 100644 --- a/source/conf.py +++ b/source/conf.py @@ -49,4 +49,4 @@ html_theme = 'alabaster' # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] \ No newline at end of file +html_static_path = ['_static'] diff --git a/source/index.rst b/source/index.rst index 99cb386..079c02e 100644 --- a/source/index.rst +++ b/source/index.rst @@ -10,6 +10,7 @@ Welcome to XenProject Governance's documentation! :maxdepth: 2 :caption: Contents: + code-of-conduct Indices and tables ================== From patchwork Fri Sep 11 12:40:05 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: George Dunlap X-Patchwork-Id: 11770471 Return-Path: Received: from mail.kernel.org (pdx-korg-mail-1.web.codeaurora.org [172.30.200.123]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id EA104159A for ; Fri, 11 Sep 2020 12:42:32 +0000 (UTC) Received: from lists.xenproject.org (lists.xenproject.org [192.237.175.120]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id BED32206DB for ; Fri, 11 Sep 2020 12:42:32 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=fail reason="signature verification failed" (1024-bit key) header.d=citrix.com header.i=@citrix.com header.b="AXTpEKoa" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org BED32206DB Authentication-Results: mail.kernel.org; dmarc=fail (p=reject dis=none) header.from=citrix.com Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=xen-devel-bounces@lists.xenproject.org Received: from localhost ([127.0.0.1] helo=lists.xenproject.org) by lists.xenproject.org with esmtp (Exim 4.92) (envelope-from ) id 1kGiMM-0006r2-7t; Fri, 11 Sep 2020 12:40:58 +0000 Received: from us1-rack-iad1.inumbo.com ([172.99.69.81]) by lists.xenproject.org with esmtp (Exim 4.92) (envelope-from ) id 1kGiML-0006qe-JM for xen-devel@lists.xenproject.org; Fri, 11 Sep 2020 12:40:57 +0000 X-Inumbo-ID: b4de2033-e08c-4e7d-b2e9-73afb4043777 Received: from esa5.hc3370-68.iphmx.com (unknown [216.71.155.168]) by us1-rack-iad1.inumbo.com (Halon) with ESMTPS id b4de2033-e08c-4e7d-b2e9-73afb4043777; Fri, 11 Sep 2020 12:40:56 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=simple/simple; d=citrix.com; s=securemail; t=1599828056; h=from:to:cc:subject:date:message-id:in-reply-to: references:mime-version:content-transfer-encoding; bh=b4TkW6rJdQqC67Ko9BJB8hryxF+queuUvVaaUxYxxmc=; b=AXTpEKoawqxIjBn5ZemMPwbW0kKsqiRIW+0+ZQnc5mit1lswRJa0GYWB TE8HSH8P+n4MzJmjcPaoIlMfA8pY6PQDaOulq8itXHKaWNCXaZ2Y1ZVT2 LRoqGheHsPGyGFPd6uBg6TgOH3YhF/vZ4XKnuRmALfhqPJs6bfRPKrLdf Y=; Authentication-Results: esa5.hc3370-68.iphmx.com; dkim=none (message not signed) header.i=none IronPort-SDR: nE/V+3M4oA58AgeCpfuVZP3O/z+lYe5CAFF60fw/KZoo6lLU2kK7IJu+lvHBIM7hW+UJpffTjH V1mSuoAu4111FxgHHIXOsaYST9WWK+WZa1Qh4Ph868GEzZwNYvgoG5GTMvGgC7RZeRxImzpFCR qcPhq3EzsbPqSAj/RKiyMs5Gi0JGEddv8/4pwxyYH6gIKHrKRx+/Lk2bXHuvZlj23Jha5sRcxk PY+sLYxCjvIoPtA9tVHc1uofvl4iUIn80B22Y69AAcZFoBUeOwGU8cEoAOlhRlHkAsXarBtrmQ G0k= X-SBRS: 2.7 X-MesageID: 26619471 X-Ironport-Server: esa5.hc3370-68.iphmx.com X-Remote-IP: 162.221.158.21 X-Policy: $RELAYED X-IronPort-AV: E=Sophos;i="5.76,415,1592884800"; d="scan'208";a="26619471" From: George Dunlap To: CC: George Dunlap Subject: [PATCH 4/8] Convert communication-guide.md to rst Date: Fri, 11 Sep 2020 13:40:05 +0100 Message-ID: <20200911124009.3760032-5-george.dunlap@citrix.com> X-Mailer: git-send-email 2.25.1 In-Reply-To: <20200911124009.3760032-1-george.dunlap@citrix.com> References: <20200911124009.3760032-1-george.dunlap@citrix.com> MIME-Version: 1.0 X-BeenThere: xen-devel@lists.xenproject.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Xen developer discussion List-Unsubscribe: , List-Post: List-Help: List-Subscribe: , Errors-To: xen-devel-bounces@lists.xenproject.org Sender: "Xen-devel" Convert headers and add necessary spaces to recognize lists. Use the :doc: tag to cross-reference documents. NB that this will throw warnings for the documents not yet converted. No textual changes. Signed-off-by: George Dunlap --- source/code-of-conduct.rst | 4 +-- ...ation-guide.md => communication-guide.rst} | 27 ++++++++++++------- source/index.rst | 1 + 3 files changed, 20 insertions(+), 12 deletions(-) rename source/{communication-guide.md => communication-guide.rst} (82%) diff --git a/source/code-of-conduct.rst b/source/code-of-conduct.rst index 81efe04..e2cdb4e 100644 --- a/source/code-of-conduct.rst +++ b/source/code-of-conduct.rst @@ -17,7 +17,7 @@ Our Standards We believe that a Code of Conduct can help create a harassment-free environment, but is not sufficient to create a welcoming environment on its own: guidance on creating a welcoming environment, how to communicate in an effective and -friendly way, etc. can be found `here `_. +friendly way, etc. can be found :doc:`here `. Examples of unacceptable behavior by participants include: @@ -97,6 +97,6 @@ https://www.contributor-covenant.org/version/1/4/code-of-conduct.html For answers to common questions about this code of conduct, see https://www.contributor-covenant.org/faq -.. _Communication Guidance: communication-guide.md +.. _Communication Guide: communication-guide.html .. _Project Governance: https://xenproject.org/developers/governance/#project-decisions .. _Contributor Covenant: https://www.contributor-covenant.org diff --git a/source/communication-guide.md b/source/communication-guide.rst similarity index 82% rename from source/communication-guide.md rename to source/communication-guide.rst index 153b100..f212c7f 100644 --- a/source/communication-guide.md +++ b/source/communication-guide.rst @@ -1,6 +1,7 @@ -# Communication Guide +Communication Guide +******************* -We believe that our [Code of Conduct](code-of-conduct.md) can help create a +We believe that our :doc:`Code of Conduct ` 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. @@ -9,16 +10,19 @@ 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 +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 +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 @@ -28,7 +32,8 @@ include: * Show empathy towards other community members * Resolve differences in opinion effectively -## Getting Help +Getting Help +============ When developing code collaboratively, technical discussion and disagreements are unavoidable. Our contributors come from different countries and cultures, @@ -38,6 +43,7 @@ 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 community @@ -47,21 +53,22 @@ To minimize such issue, we provide a 3-stage process 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 obligated +:doc:`Code of Conduct `. In addition, team members are obligated 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 case, please make certain that you highlight the nature of a request by making sure that either help or mediation is mentioned in the e-mail subject or body. -## Specific Topics and Best Practice +Specific Topics and Best Practice +================================= -* [Code Review Guide](code-review-guide.md): +* :doc:`Code Review Guide `: Essential reading for code reviewers and contributors -* [Communication Best Practice](communication-practice.md): +* :doc:`Communication Best Practice `: This guide covers communication guidelines for code reviewers and authors. It should help you create self-awareness, anticipate, avoid and help resolve communication issues. -* [Resolving Disagreement](resolving-disagreement.md): +* :doc:`Resolving Disagreement `: This guide lays out common situations that can lead to dead-lock and shows common patterns on how to avoid and resolve issues. diff --git a/source/index.rst b/source/index.rst index 079c02e..e0139fa 100644 --- a/source/index.rst +++ b/source/index.rst @@ -11,6 +11,7 @@ Welcome to XenProject Governance's documentation! :caption: Contents: code-of-conduct + communication-guide Indices and tables ================== From patchwork Fri Sep 11 12:40:06 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: George Dunlap X-Patchwork-Id: 11770465 Return-Path: Received: from mail.kernel.org (pdx-korg-mail-1.web.codeaurora.org [172.30.200.123]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 372E9618 for ; Fri, 11 Sep 2020 12:42:16 +0000 (UTC) Received: from lists.xenproject.org (lists.xenproject.org [192.237.175.120]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id EC494206DB for ; Fri, 11 Sep 2020 12:42:15 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=fail reason="signature verification failed" (1024-bit key) header.d=citrix.com header.i=@citrix.com header.b="SLyd6mbp" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org EC494206DB Authentication-Results: mail.kernel.org; dmarc=fail (p=reject dis=none) header.from=citrix.com Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=xen-devel-bounces@lists.xenproject.org Received: from localhost ([127.0.0.1] helo=lists.xenproject.org) by lists.xenproject.org with esmtp (Exim 4.92) (envelope-from ) id 1kGiMC-0006mA-PX; Fri, 11 Sep 2020 12:40:48 +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.92) (envelope-from ) id 1kGiMB-0006gu-Ec for xen-devel@lists.xenproject.org; Fri, 11 Sep 2020 12:40:47 +0000 X-Inumbo-ID: ebeda99d-dabe-4cfb-8a1a-6f4b21e6e3ef Received: from esa3.hc3370-68.iphmx.com (unknown [216.71.145.155]) by us1-amaz-eas2.inumbo.com (Halon) with ESMTPS id ebeda99d-dabe-4cfb-8a1a-6f4b21e6e3ef; Fri, 11 Sep 2020 12:40:41 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=simple/simple; d=citrix.com; s=securemail; t=1599828042; h=from:to:cc:subject:date:message-id:in-reply-to: references:mime-version:content-transfer-encoding; bh=6hvqvDnIaK5LxdUrZAah3lW8EHE+s21vV+EQh3ktnEA=; b=SLyd6mbpgL38uxI6IpZGMsMAe7dXtdWTjf2V52ePTCvH3QHXwcfv5O8c soYfVvgIa8NGuFES5cugxOqGvgqwBb/Lf2EDiaAfxUCvX2MTesfm0+P78 m43UixC6T+wGLXcukZO/LB1w45YQHwV/3MUzck1hUtJV/b5ND4aVYT/RI M=; Authentication-Results: esa3.hc3370-68.iphmx.com; dkim=none (message not signed) header.i=none IronPort-SDR: +mZGLqzCxjx21jiSZNMzHII0A3m3GkZ+yoody6L/5j9Sh6cxVfy6N83IVqG3P8hpkhysd3IR69 6zFNODLX6HYCv/hOldhxKl7nOWoK/2ZAxT2vL1/JAkOSsjEQGqgt2vJtrKmLTxzXgfVE4BA6A8 DtYHifLndYyKtfw5X/YwQxWOg3Ft9Pa128UmtdWqcZFp5EiDltaONOH5fMOjS/td+93FoQB4M1 Bd2LK9O3Xnx0X8oeTRmnZWN2CkiYJu8CeLHeJqeIopHI8bS34iOUOv+0EOyg42uemEZ7uUi3Wd pcQ= X-SBRS: 2.7 X-MesageID: 26476155 X-Ironport-Server: esa3.hc3370-68.iphmx.com X-Remote-IP: 162.221.158.21 X-Policy: $RELAYED X-IronPort-AV: E=Sophos;i="5.76,415,1592884800"; d="scan'208";a="26476155" From: George Dunlap To: CC: George Dunlap Subject: [PATCH 5/8] Convert code-review-guide.md to rst Date: Fri, 11 Sep 2020 13:40:06 +0100 Message-ID: <20200911124009.3760032-6-george.dunlap@citrix.com> X-Mailer: git-send-email 2.25.1 In-Reply-To: <20200911124009.3760032-1-george.dunlap@citrix.com> References: <20200911124009.3760032-1-george.dunlap@citrix.com> MIME-Version: 1.0 X-BeenThere: xen-devel@lists.xenproject.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Xen developer discussion List-Unsubscribe: , List-Post: List-Help: List-Subscribe: , Errors-To: xen-devel-bounces@lists.xenproject.org Sender: "Xen-devel" Convert titles as approproate. Use inter-doc references for other full docs. Convert other external links to RST-style references, keeping the labels (3-F). One exception to this: sphinx noticed that there were two 'D' labels; rename one to `Shift Left`. Convert internal link to RST-style reference. Add spaces so that lists compile correctly. Remove explicit HTML
tags; Make them a separate block to achieve a similar goal. Convert "manual" **subsubsection** sections to RST subsubsuctions (^^^^^). No textual changes. Signed-off-by: George Dunlap --- ...-review-guide.md => code-review-guide.rst} | 153 +++++++++++------- source/index.rst | 1 + 2 files changed, 97 insertions(+), 57 deletions(-) rename source/{code-review-guide.md => code-review-guide.rst} (79%) diff --git a/source/code-review-guide.md b/source/code-review-guide.rst similarity index 79% rename from source/code-review-guide.md rename to source/code-review-guide.rst index ed4f9d6..9c0040e 100644 --- a/source/code-review-guide.md +++ b/source/code-review-guide.rst @@ -1,4 +1,5 @@ -# Code Review Guide +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 provides @@ -14,40 +15,46 @@ provides pointers on code author's and reviewer's workflows. Sometimes it happens that a submitted patch series made wrong assumptions or has a flawed design or architecture. This can be frustrating for contributors and -code reviewers. Note that this document does contain [a section](#problems) -that provides suggestions on how to minimize the impact for most stake-holders +code reviewers. Note that this document does contain `a section `_ +that provides suggestions on how to minimize the impact for most stake-holders and also on how to avoid such situations. This document does **not cover** the following topics: -* [Communication Best Practice][1] -* [Resolving Disagreement][2] -* [Patch Submission Workflow][3] -* [Managing Patch Submission with Git][4] -## What we look for in Code Reviews +* :doc:`Communication Best Practice ` +* :doc:`Resolving Disagreement ` +* `Patch Submission Workflow <3_>`_ +* `Managing Patch Submission with Git <4_>`_ + +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 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 +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 +Functionality +------------- * Does it do what it’s trying to do? * Is it doing it in the most efficient way? * Does it handle all the corner / error cases correctly? -### Maintainability / Robustness +Maintainability / Robustness +---------------------------- * Is the code clear? Appropriately commented? * Does it duplicate another piece of code? @@ -61,60 +68,75 @@ and/or robustness issues. In such cases, maintainers may ask you to make additional changes, such that your submitted code does not make things worse or point you to other patches are already being worked on. -### System properties +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 +Style +----- * Comments, carriage returns, **snuggly braces**, &c -* See [CODING_STYLE][5] and [tools/libxl/CODING_STYLE][6] +* See `CODING_STYLE <5_>`_ and `tools/libxl/CODING_STYLE <6_>`_ * No extraneous whitespace changes -### Documentation and testing +Documentation and testing +------------------------- * If there is pre-existing documentation in the tree, such as man pages, design documents, etc. a contributor may be asked to update the documentation - alongside the change. Documentation is typically present in the [docs][7] + alongside the change. Documentation is typically present in the `docs <7_>`_ folder. * When adding new features that have an impact on the end-user, - a contributor should include an update to the [SUPPORT.md][8] file. + a contributor should include an update to the `SUPPORT.md <8_>`_ 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 +Testing for the Xen Project Hypervisor +-------------------------------------- Tests are typically located in one of the following directories -* **Unit tests**: [tools/tests][9] or [xen/test][A]
+ +* **Unit tests**: `tools/tests <9_>`_ or `xen/test `_ + Unit testing is hard for a system like Xen and typically requires building 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][B]
+ +* **Build and smoke test**: see `Xen GitLab CI `_ + Runs build tests for a combination of various distros and compilers against changes committed to staging. Developers can join as members and test their development branches **before** submitting a patch. -* **XTF tests** (microkernel-based tests): see [XTF][C]
+ +* **XTF tests** (microkernel-based tests): see `XTF `_ + XTF has been designed to test interactions between your software and hardware. It is a very useful tool for testing low level functionality and is executed as part of the project's CI system. XTF can be easily executed locally on xen.git trees. -* **osstest**: see [README][D]
+ +* **osstest**: see `README `_ + 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 **after** they have been reviewed. A contributor’s changes **cannot be applied to master** unless the tests pass this test suite. Note that XTF and other tests are also executed as part of osstest. -### Patch / Patch series information +Patch / Patch series information +-------------------------------- * Informative one-line changelog * Full changelog @@ -124,14 +146,16 @@ Tests are typically located in one of the following directories * Reviewed-by’s and Acked-by’s dropped if appropriate More information related to these items can be found in our -[Patch submission Guide][E]. +`Patch submission Guide `_. -## Code Review Workflow +Code Review Workflow +==================== This section is important for code authors and reviewers. We recommend that in particular new code authors carefully read this section. -### Workflow from a Reviewer's Perspective +Workflow from a Reviewer's Perspective +-------------------------------------- Patch series typically contain multiple changes to the codebase, some transforming the same section of the codebase multiple times. It is quite common @@ -147,7 +171,8 @@ Generally there are no hard rules on how to structure a series, as the structure of a series is very code specific and it is hard to give specific advice. There are some general tips which help and some general patterns. -**Tips:** +Tips +^^^^ * Outline the thinking behind the structure of the patch series. This can make a huge difference and helps ensure that the code reviewer understands what the @@ -161,7 +186,8 @@ are some general tips which help and some general patterns. to learn the tools, code and deal with a large patch series all together for the first time. -**General Patterns:** +General Patterns +^^^^^^^^^^^^^^^^ If there are multiple subsystems involved in your series, then these are best separated out into **sets of patches**, which roughly follow the following @@ -171,6 +197,7 @@ all subsystems (e.g. headers, macros, documentation) impacting all changed subsystems which ideally comes **before** subsystem specific changes. The seven categories typically making up a logical set of patches + 1. Cleanups and/or new Independent Helper Functions 2. Reorganizations 3. Headers, APIs, Documentation and anything which helps understand the @@ -189,13 +216,15 @@ patches. If a series is structured this way, it is often possible to agree early on, that a significant portion of the changes are fine and to check these in independently of the rest of the patch series. This means that there is + * Less work for authors to rebase * Less cognitive overhead for reviewers to review successive versions of a series * The possibility for different code reviewers to review portions of such large changes independently -**Trade-Offs:** +Trade-Offs +^^^^^^^^^^ * In some cases, following the general pattern above may create extra patches and may make a series more complex and harder to understand. @@ -210,9 +239,12 @@ independently of the rest of the patch series. This means that there is the change** is back-ported, whereas general cleanups and improvements are not. -**Example:** -* [[PATCH v3 00/18] VM forking][H] is a complex patch series with an exemplary +Example +^^^^^^^ + +* `[PATCH v3 00/18] VM forking `_ is a complex patch series with an exemplary cover letter. Notably, it contains the following elements + * It provides a description of the design goals and detailed description of the steps required to fork a VM. * A description of changes to the user interface @@ -225,7 +257,8 @@ independently of the rest of the patch series. This means that there is rest of the series and **4** the substance of the series with additional information to make it easier for the reviewer to parse the series. -### Workflow from an Author's Perspective +Workflow from an Author's Perspective +------------------------------------- When code authors receive feedback on their patches, they typically first try to clarify feedback they do not understand. For smaller patches or patch series @@ -236,18 +269,22 @@ make sense to send out a new revision earlier. As a reviewer, you need some system that helps ensure that you address all review comments. This can be tedious when trying to map a hierarchical e-mail thread onto a code-base. Different people use different techniques from using + * In-code TODO statements with comment snippets copied into the code * To keeping a separate TODO list * To printing out the review conversation tree and ticking off what has been addressed * A combination of the above -### Problematic Patch Reviews +.. _problems: + +Problematic Patch Reviews +------------------------- A typical waterfall software development process is sequential with the following steps: define requirements, analyze, design, code, test and deploy. Problems uncovered by code review or testing at such a late stage can cause -costly redesign and delays. The principle of **[Shift Left][D]** is to take a +costly redesign and delays. The principle of `Shift Left`_ is to take a task that is traditionally performed at a late stage in the process and perform that task at earlier stages. The goal is to save time by avoiding refactoring. @@ -271,43 +308,45 @@ separate difficult and easy portions of a patch series. This will enable reviewers to progress uncontroversial portions of a patch independently from controversial ones. -### Reviewing for Patch Authors +Reviewing for Patch Authors +--------------------------- The following presentation by George Dunlap, provides an excellent overview 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 members The presentation demonstrates that you do not need to worry about any of these concerns. In addition, reviewing other people's patches helps you + * write better patches and experience the code review process from the other side * and build more influence within the community over time Thus, we recommend strongly that **patch authors** read the watch the recording or read the slides: -* [Patch Review for Non-Maintainers slides][F] -* [Patch Review for Non-Maintainers recording - 20"][G] - -[1]: communication-practice.md -[2]: resolving-disagreement.md -[3]: https://wiki.xenproject.org/wiki/Submitting_Xen_Project_Patches -[4]: https://wiki.xenproject.org/wiki/Managing_Xen_Patches_with_Git -[5]: https://xenbits.xenproject.org/gitweb/?p=xen.git;a=blob;f=CODING_STYLE -[6]: https://xenbits.xenproject.org/gitweb/?p=xen.git;a=blob;f=tools/libxl/CODING_STYLE -[7]: https://xenbits.xenproject.org/gitweb/?p=xen.git;a=tree;f=docs -[8]: https://xenbits.xenproject.org/gitweb/?p=xen.git;a=blob;f=SUPPORT.md -[9]: https://xenbits.xenproject.org/gitweb/?p=xen.git;a=tree;f=tools/tests -[A]: https://xenbits.xenproject.org/gitweb/?p=xen.git;a=tree;f=xen/test -[B]: https://gitlab.com/xen-project/xen/pipelines -[C]: https://xenbits.xenproject.org/docs/xtf/ -[D]: https://xenbits.xenproject.org/gitweb/?p=osstest.git;a=blob;f=README -[E]: https://wiki.xenproject.org/wiki/Submitting_Xen_Project_Patches -[D]: https://devopedia.org/shift-left -[F]: https://www.slideshare.net/xen_com_mgr/xpdds19-keynote-patch-review-for-nonmaintainers-george-dunlap-citrix-systems-uk-ltd -[G]: https://www.youtube.com/watch?v=ehZvBmrLRwg -[H]: https://lists.xenproject.org/archives/html/xen-devel/2019-12/threads.html#02097 + +* `Patch Review for Non-Maintainers slides `_ +* `Patch Review for Non-Maintainers recording - 20" `_ + +.. _3: https://wiki.xenproject.org/wiki/Submitting_Xen_Project_Patches +.. _4: https://wiki.xenproject.org/wiki/Managing_Xen_Patches_with_Git +.. _5: https://xenbits.xenproject.org/gitweb/?p=xen.git;a=blob;f=CODING_STYLE +.. _6: https://xenbits.xenproject.org/gitweb/?p=xen.git;a=blob;f=tools/libxl/CODING_STYLE +.. _7: https://xenbits.xenproject.org/gitweb/?p=xen.git;a=tree;f=docs +.. _8: https://xenbits.xenproject.org/gitweb/?p=xen.git;a=blob;f=SUPPORT.md +.. _9: https://xenbits.xenproject.org/gitweb/?p=xen.git;a=tree;f=tools/tests +.. _A: https://xenbits.xenproject.org/gitweb/?p=xen.git;a=tree;f=xen/test +.. _B: https://gitlab.com/xen-project/xen/pipelines +.. _C: https://xenbits.xenproject.org/docs/xtf/ +.. _D: https://xenbits.xenproject.org/gitweb/?p=osstest.git;a=blob;f=README +.. _E: https://wiki.xenproject.org/wiki/Submitting_Xen_Project_Patches +.. _Shift Left: https://devopedia.org/shift-left +.. _F: https://www.slideshare.net/xen_com_mgr/xpdds19-keynote-patch-review-for-nonmaintainers-george-dunlap-citrix-systems-uk-ltd +.. _G: https://www.youtube.com/watch?v=ehZvBmrLRwg +.. _H: https://lists.xenproject.org/archives/html/xen-devel/2019-12/threads.html#02097 diff --git a/source/index.rst b/source/index.rst index e0139fa..d1152c4 100644 --- a/source/index.rst +++ b/source/index.rst @@ -12,6 +12,7 @@ Welcome to XenProject Governance's documentation! code-of-conduct communication-guide + code-review-guide Indices and tables ================== From patchwork Fri Sep 11 12:40:07 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: George Dunlap X-Patchwork-Id: 11770459 Return-Path: Received: from mail.kernel.org (pdx-korg-mail-1.web.codeaurora.org [172.30.200.123]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 16FD3618 for ; Fri, 11 Sep 2020 12:41:58 +0000 (UTC) Received: from lists.xenproject.org (lists.xenproject.org [192.237.175.120]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id D4863206DB for ; Fri, 11 Sep 2020 12:41:57 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=fail reason="signature verification failed" (1024-bit key) header.d=citrix.com header.i=@citrix.com header.b="RWhkY695" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org D4863206DB Authentication-Results: mail.kernel.org; dmarc=fail (p=reject dis=none) header.from=citrix.com Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=xen-devel-bounces@lists.xenproject.org Received: from localhost ([127.0.0.1] helo=lists.xenproject.org) by lists.xenproject.org with esmtp (Exim 4.92) (envelope-from ) id 1kGiMR-0006vQ-Ra; Fri, 11 Sep 2020 12:41:03 +0000 Received: from us1-rack-iad1.inumbo.com ([172.99.69.81]) by lists.xenproject.org with esmtp (Exim 4.92) (envelope-from ) id 1kGiMQ-0006qe-IF for xen-devel@lists.xenproject.org; Fri, 11 Sep 2020 12:41:02 +0000 X-Inumbo-ID: c6cb94da-1a8c-4698-b869-f9dd9ee092a4 Received: from esa5.hc3370-68.iphmx.com (unknown [216.71.155.168]) by us1-rack-iad1.inumbo.com (Halon) with ESMTPS id c6cb94da-1a8c-4698-b869-f9dd9ee092a4; Fri, 11 Sep 2020 12:40:57 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=simple/simple; d=citrix.com; s=securemail; t=1599828057; h=from:to:cc:subject:date:message-id:in-reply-to: references:mime-version:content-transfer-encoding; bh=pY3fjy1kW4dEaaeHdIdYk6Yk6eEyrBmlLZyryCF70Go=; b=RWhkY695GFPZNjQElWD9Q07pSABfXnzwQHWlIaVZf8c64A3NT4/AdC6d ZaqXTJ3SpoZR7iyZJz0KZmoanVAurrIZLZ9xhlgG8a4w6y+xL5nDxWBlV vVNurpD5W1tmBF3lRLst/kqdwbaxx5QT0xv4qvOVypc/L7nonwjIBZsY6 8=; Authentication-Results: esa5.hc3370-68.iphmx.com; dkim=none (message not signed) header.i=none IronPort-SDR: Xf6xs1/ysMfZiCJGgLjUh04akENusDgLSuMcKvBh2K6sakLh5E/bMqAsxzdeTU40281Uxrsz05 L0/+Jnrppy2ld++U+4IWIpLr+Tp+WOP8PqpuyR5xAxxG78XWMaERrwiwoLK+VmgzNXOgxnvOjE IUpYu4y94f4MudpaepB9e+EVsrB1cqq5uWQLHFDrVvD505XLh1IjV8APD1HEXAg9RMXMDO8LrX uejf1s3AsqC8ZICuvlXqM8pj0Z/XAd6wNIvN/rjtMwBobk2vNlpqz9Y7YI/VVj4LBF9VRdZ0XY 9mw= X-SBRS: 2.7 X-MesageID: 26619473 X-Ironport-Server: esa5.hc3370-68.iphmx.com X-Remote-IP: 162.221.158.21 X-Policy: $RELAYED X-IronPort-AV: E=Sophos;i="5.76,415,1592884800"; d="scan'208";a="26619473" From: George Dunlap To: CC: George Dunlap Subject: [PATCH 6/8] Convert communication-practice.md to RST Date: Fri, 11 Sep 2020 13:40:07 +0100 Message-ID: <20200911124009.3760032-7-george.dunlap@citrix.com> X-Mailer: git-send-email 2.25.1 In-Reply-To: <20200911124009.3760032-1-george.dunlap@citrix.com> References: <20200911124009.3760032-1-george.dunlap@citrix.com> MIME-Version: 1.0 X-BeenThere: xen-devel@lists.xenproject.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Xen developer discussion List-Unsubscribe: , List-Post: List-Help: List-Subscribe: , Errors-To: xen-devel-bounces@lists.xenproject.org Sender: "Xen-devel" Convert title / sections, list formatting, and references as appropriate. Convert >-based blockquotes to RST-style block quotes. Apply the following style manually: * Each quote should be a separate block quote para * Quotes should be italicized. Labels ("BAD:") will be bold. For the "expressing approval" thing, put it in a "literal" block so that the colons line up. Disable syntax highlighting by default. No textual changes. Signed-off-by: George Dunlap --- ...practice.md => communication-practice.rst} | 287 +++++++++++------- source/conf.py | 2 + source/index.rst | 1 + 3 files changed, 182 insertions(+), 108 deletions(-) rename source/{communication-practice.md => communication-practice.rst} (75%) diff --git a/source/communication-practice.md b/source/communication-practice.rst similarity index 75% rename from source/communication-practice.md rename to source/communication-practice.rst index 19ddf66..3ccc087 100644 --- a/source/communication-practice.md +++ b/source/communication-practice.rst @@ -1,15 +1,19 @@ -# Communication Best Practice +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’s communication style and culture * Show empathy towards other community members -## Code reviews for **reviewers** and **patch authors** +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 when a reviewer did not intend to do so. Feeling defensive is a normal reaction to a critique or feedback. A reviewer should be aware of how the pitch, tone, @@ -28,7 +32,8 @@ Before embarking on a code review, it is important to remember that are all trying to create a productive, welcoming and agile environment, we do not always succeed. -### Express appreciation +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 @@ -40,21 +45,28 @@ sets the tone for the rest of the code review. Starting **every** review on a positive 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 + + *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 + + *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 + + *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 phrases, 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 + + *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 place to do this, is at the top of a patch, as addressing code review comments @@ -68,13 +80,17 @@ interpreted as such. Appreciation should also be expressed by patch authors when asking for clarifications to a review or responding to questions. A simple -> Thank you for your feedback -> Thank you for your reply -> Thank you XXX! + + *Thank you for your feedback* + + *Thank you for your reply* + + *Thank you XXX!* is normally sufficient. -### Avoid inflammatory and negatively charged language +Avoid inflammatory and negatively charged language +-------------------------------------------------- The way a reviewer expresses feedback, has a big impact on how the author perceives the feedback. Choosing negatively charged language such as your code @@ -84,12 +100,12 @@ communication difficult. 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 has -come across the most strongly-worded dictionary entry [he has ever seen][1]. +come across the most strongly-worded dictionary entry `he has ever seen <1_>`_. This example illustrates the differences between an inflammatory and fact-based description extremely well. -> 裹脚 (guo3 jiao3): foot-binding (a vile feudal practice which crippled women -> both physically and spiritually) + *裹脚 (guo3 jiao3): foot-binding (a vile feudal practice which 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 @@ -99,16 +115,16 @@ by this statement. The main take-away is that the author of the dictionary entry had strong opinions about this topic. It does not tell you why you should have the same opinion. -Compare this to the [Wikipedia entry][2] +Compare this to the `Wikipedia entry <2_>`_ -> Foot binding was the custom of applying tight binding to the feet of young -> 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 disabilities 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. …The toes on each foot -> were curled under, then pressed with great force downwards and squeezed -> into the sole of the foot until [redacted] ... + *Foot binding was the custom of applying tight binding to the feet of young + 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 disabilities 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. …The toes on each foot + were curled under, then pressed with great force downwards and squeezed + into the sole of the foot until [redacted] ...* Without going into the details of foot-binding, it is noticeable that the definition is a list of simple facts that are laid out in a way that make it @@ -118,10 +134,13 @@ Because the Wikipedia entry is entirely fact based it is more powerful and persuasive than the dictionary entry. The same applies to code reviews. Making statements in code reviews such as -> Your code is garbage -> This idea is stupid + + *Your code is garbage* + + *This idea is stupid* besides negatively charged, rude and counter productive + * It will make the patch author angry: instead of finding a solution to the problem the author will spend time and mental energy wrestling with their feelings @@ -129,16 +148,21 @@ besides negatively charged, rude and counter productive * 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 figure out what was going on here + + *This piece of code is confusing* + + *It took me a long time to figure 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. + + **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 lead to disagreements on the best architecture, design or coding pattern. As already @@ -146,33 +170,40 @@ pointed out in this section: avoid feedback that is opinion-based and thus does not add any value. Back your criticism (or idea on how to solve a problem) with a sensible rationale. -### Review the code, not the person +Review the code, not the person +------------------------------- Without realizing it, it is easy to overlook the difference between insightful critique of code and personal criticism. Let's look at a theoretical function where there is an opportunity to return out of the function early. In this case, you could say -> You should return from this function early, because of XXX + *You should return from this function early, because of XXX* On its own, there is nothing wrong with this statement. However, a code review 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 avoids this issue: -> Returning from this function early is better, because of XXX + *Returning from this function early is better, because of XXX* Without personal reference, a code review will communicate the problem, idea or issue without risking mis-interpretation. -### Verbose vs. terse +Verbose vs. terse +----------------- Due to the time it takes to review and compose code reviewer, reviewers often 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 + + *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 @@ -194,7 +225,8 @@ style and ask whether the author is OK with it. In almost all cases, they will be: by asking you are showing empathy that helps counteract a negative impression. -### Clarity over verbosity +Clarity over verbosity +---------------------- When reading this document, you may get the impression that following the guidance outlined here takes more effort and time for both code reviewers and @@ -204,21 +236,26 @@ iterations during communication. We value **clarity over verbosity**. Areas which often create unnecessary back-and-forth between reviewers and authors are + * Unstated assumptions and goals * Leave suggestions, examples, and resources (such as links to existing code) * There is nothing more helpful for the thought process than example. It guarantees that you have a shared understanding and reduces the questions asked on a comment. -### Code Review Comments should be actionable +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 identified. Statements such as -> BAD: This is wrong -> BAD: This does not work -> BETTER, BUT NOT GOOD: This does not work, because of XXX + + **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 send out a new patch version. By doing this, you essentially force the patch author @@ -227,29 +264,34 @@ 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 + *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 solution. As a reviewer you should be as up-front and possible in such a case and say something 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 what -> works best + *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 what + works best* -### Identify the severity and optionality of review comments +Identify the severity and optionality of review comments +-------------------------------------------------------- By default, every comment which is made **ought to be addressed** by the author. However, sometimes reviewers note issues, which would be nice if they were addressed, but are not mandatory to fix. Typically, reviewers use terminology such as -> This would be a nice-to-have -> This is not a blocker + + *This would be a nice-to-have* + + *This is not a blocker* Some maintainers use -> NIT: XXX + + *NIT: XXX* however, it is sometimes also used to indicate a minor issue that **must** be fixed. Also terminology such as **this is not a blocker** could be @@ -258,35 +300,42 @@ clear whether a comment is an optional suggestion. Examples may be > NIT (optional): XXX > I think it would be good if X also did Y, not a requirement but nice-to-have -### Identify the severity of a disagreement +Identify the severity of a disagreement +--------------------------------------- During a code review, it can happen that reviewer and author disagree on how to move forward. The default position when it comes to disagreements is that **both 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][3] to highlight one's position on -proposals, formal or informal votes using the 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 +Within the Xen Project, we have `a way <3_>`_ to highlight one's position on +proposals, formal or informal votes using the 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 + + *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 + *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 changes you are going to make: + * Simply send the next version with the changes addressed and record it in the change-log @@ -297,22 +346,26 @@ exceptionally long. In cases where there was discussion and maybe disagreement, it does however make sense to close the discussion by saying something like -> ACK -> Seems we are agreed, I am going to do this + *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 followed or not. -### Avoid uncommon words: not everyone is a native English speaker +Avoid uncommon words: not everyone is a native English speaker +-------------------------------------------------------------- Avoid uncommon words both when reviewing code or responding to a review. Not everyone is a native English speaker. The use of such words can come across badly and can lead to misunderstandings. -### Prioritize significant flaws +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 @@ -326,15 +379,17 @@ establish and agree whether a series or part of a series has a significant flaw and agree a course of action. A pragmatic approach would be to + * Highlight problematic portions of a series in the cover letter * For the patch author and reviewer(s) to agree that for problematic to omit style and minor issues in the review, until the significant flaw is addressed This saves both the patch author and reviewer(s) time. Note that some -background is covered in detail in [Problematic Patch Reviews][4]. +background is covered in detail in `Problematic Patch Reviews <4_>`_. -### Reviewers: Welcome newcomers +Reviewers: 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 @@ -343,6 +398,7 @@ relationship in the long term. When someone does their first code submission, they will not be familiar with **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 @@ -350,21 +406,23 @@ When someone does their first code submission, they will not be familiar with process makes the process more seamless for the contributor. So, you could say something 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 IRC -> handle is ZZZ + *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 IRC + handle is ZZZ* -### Reviewers: Take account of previous reviewer(s) comments +Reviewers: Take account of previous reviewer(s) comments +-------------------------------------------------------- Sometimes multiple reviewers share reviewing a series. For example, reviewer John has reviewed the first 5 iterations of the series. The patch author has addressed all of John's comments and Susan comes in and picks up the series after iteration 5. In such cases it is possible that John and Susan have different styles, such as + * different preferences on the code layout * different preferences on code style @@ -374,12 +432,13 @@ code author. In addition, it also causes extra work for Susan. The easiest way to avoid such situations, would be for Susan to focus on faulty code only and to disregard personal preferences when taking over the review of a series. -### Reviewers: Review the code, then review the review +Reviewers: Review the code, then review the review +-------------------------------------------------- As stated earlier it is often difficult to mentally separate finding issues from articulating code review comments in a constructive and positive manner. Even as an experienced code reviewer you can be in a bad mood, which can - impact your communication style. +impact your communication style. A good trick to avoid this, is to start and complete the code review and then **not send it immediately**. You can then have a final go over the code review @@ -391,21 +450,24 @@ scan before pressing the send button. Generally, it is a good idea for code reviewers to do this regularly, purely from the viewpoint of self-improvement and self-awareness. -## Common Communication Pitfalls +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 affect **all** online communication. As such, we can only try and do our best. -### Misunderstandings +Misunderstandings +----------------- When you meet face to face, you can read a person’s emotions. Even with a phone call, someone’s tone of voice can convey a lot of information. Using on-line communication channels you are flying blind, which often leads to -misunderstandings. [Research][5] shows that in up to 50% of email +misunderstandings. `Research <5_>`_ shows that in up to 50% of email conversations, the tone of voice is misinterpreted. In code reviews and technical discussions in general we tend to see two things + * The reviewer or author interprets an exchange as too critical, passive aggressive, or other: this usually comes down to different cultures and communication styles, which are covered in the next section @@ -415,22 +477,25 @@ In the latter case, the key to resolution is to **identify the misunderstanding** as quickly as possible and call it out and de-escalate rather than let the misunderstanding linger. This is inherently difficult and requires more care than normal communication. Typically you would start with + * Showing appreciation * Highlighting the potential misunderstanding and verifying whether the other person also feels that maybe there was a misunderstanding * Proposing a way forward: for example, it may make sense to move the - conversation from the mailing list to [IRC][6] either in private or public, + conversation from the mailing list to `IRC <6_>`_ 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 communication 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 + + *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 what is to be achieved @@ -443,9 +508,10 @@ caused 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][7]. +outlined in :doc:`Resolving Disagreement `. -### Cultural differences and different communication styles +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 factor @@ -458,48 +524,53 @@ especially in sensitive situations such as conflict resolution, giving and receiving feedback, and consensus building. For example, giving direct feedback such as -> [Please] replace XXX with YYY, as XXX does not do ZZZ + + *[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 the following would be used -> This looks very good to me, but I believe you should use YYY here, -> because XXX would.... + + *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 cultural 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 currently popular, with the most well-known one being -[Erin Meyer's Culture Map][8]. A short overview can be found [here][9] +`Erin Meyer's Culture Map <8_>`_. A short overview can be found `here <9_>`_ (33 slides). -### Code reviews and discussions are not competitions +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 +Resolving Disagreement Effectively +---------------------------------- -Common scenarios are covered our guide on [Resolving Disagreement][7], which +Common scenarios are covered our guide on :doc:`Resolving Disagreement `, which lays out situations that can lead to dead-lock and shows common patterns on how to avoid and resolve issues. -[1]: https://youtu.be/ehZvBmrLRwg?t=834 -[2]: https://en.wikipedia.org/wiki/Foot_binding -[3]: https://xenproject.org/developers/governance/#expressingopinion -[4]: resolving-disagreement.md#problems -[5]: https://www.wired.com/2006/02/the-secret-cause-of-flame-wars/ -[6]: https://xenproject.org/help/irc/ -[7]: resolving-disagreement.md -[8]: https://en.wikipedia.org/wiki/Erin_Meyer -[9]: https://www.nsf.gov/attachments/134059/public/15LFW_WorkingWithMulticulturalTeams_LarsonC.pdf +.. _1: https://youtu.be/ehZvBmrLRwg?t=834 +.. _2: https://en.wikipedia.org/wiki/Foot_binding +.. _3: https://xenproject.org/developers/governance/#expressingopinion +.. _4: resolving-disagreement.md#problems +.. _5: https://www.wired.com/2006/02/the-secret-cause-of-flame-wars/ +.. _6: https://xenproject.org/help/irc/ +.. _8: https://en.wikipedia.org/wiki/Erin_Meyer +.. _9: https://www.nsf.gov/attachments/134059/public/15LFW_WorkingWithMulticulturalTeams_LarsonC.pdf diff --git a/source/conf.py b/source/conf.py index 85bcedb..b63b196 100644 --- a/source/conf.py +++ b/source/conf.py @@ -50,3 +50,5 @@ html_theme = 'alabaster' # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ['_static'] + +highlight_language = 'none' diff --git a/source/index.rst b/source/index.rst index d1152c4..be162cf 100644 --- a/source/index.rst +++ b/source/index.rst @@ -13,6 +13,7 @@ Welcome to XenProject Governance's documentation! code-of-conduct communication-guide code-review-guide + communication-practice Indices and tables ================== From patchwork Fri Sep 11 12:40:08 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: George Dunlap X-Patchwork-Id: 11770447 Return-Path: Received: from mail.kernel.org (pdx-korg-mail-1.web.codeaurora.org [172.30.200.123]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 04E1E92C for ; Fri, 11 Sep 2020 12:41:24 +0000 (UTC) Received: from lists.xenproject.org (lists.xenproject.org [192.237.175.120]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id BBC2622206 for ; Fri, 11 Sep 2020 12:41:23 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=fail reason="signature verification failed" (1024-bit key) header.d=citrix.com header.i=@citrix.com header.b="Os6tkyv6" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org BBC2622206 Authentication-Results: mail.kernel.org; dmarc=fail (p=reject dis=none) header.from=citrix.com Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=xen-devel-bounces@lists.xenproject.org Received: from localhost ([127.0.0.1] helo=lists.xenproject.org) by lists.xenproject.org with esmtp (Exim 4.92) (envelope-from ) id 1kGiMO-0006sr-IG; Fri, 11 Sep 2020 12:41:00 +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.92) (envelope-from ) id 1kGiMN-0006sF-RY for xen-devel@lists.xenproject.org; Fri, 11 Sep 2020 12:40:59 +0000 X-Inumbo-ID: 53a1ccb8-79e9-46d0-ad57-45f95cbe189b Received: from esa5.hc3370-68.iphmx.com (unknown [216.71.155.168]) by us1-amaz-eas2.inumbo.com (Halon) with ESMTPS id 53a1ccb8-79e9-46d0-ad57-45f95cbe189b; Fri, 11 Sep 2020 12:40:58 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=simple/simple; d=citrix.com; s=securemail; t=1599828058; h=from:to:cc:subject:date:message-id:in-reply-to: references:mime-version:content-transfer-encoding; bh=o3n0ohLD5vGC2tAdR+K+unPc6Jc5i/h6YYF+bO959Yg=; b=Os6tkyv6dAhx2bHaABdVn8+s1lCVRWEkWXNhcpffmzird3rGD2b00vuA 7IE4xRO1cMF/QLIPm44z9FByGxDyK6jtAFx+gLUSrl/3J/ybGKaEJqd2o MHKP5qXydGeyHecO5GpZ+BfiQTqxmXtTITWVvatVbq1P0OJ8vyNTepRUH M=; Authentication-Results: esa5.hc3370-68.iphmx.com; dkim=none (message not signed) header.i=none IronPort-SDR: 97ln0Ay0Wi5aYYPYk8+iBUnko0+ut7IiHGtILZqx8FRQnoLiZSuCqD9ryeimyC7unKtPFhjn2X aNI+CSd7P+R/tFs+zGRZ7EM42MUYmTgJXhVt5fOaaocw2JAV5NF2SGRmsOUr7ROVHSnBpUpGle U3umSmLphRwOlv9H+tyXmEGwiF02FSNYP2Pg1IpZwNDe9C1WE2M7c0n07q19+TqcIxueyTl+Ff 2SbjE7b5OXztjwpUFdCI4kLaWEJEONbh3ZEkSaDncGwIiFWBusKk/ct0XhdAV+4VyIpVZdkk2N HJs= X-SBRS: 2.7 X-MesageID: 26619472 X-Ironport-Server: esa5.hc3370-68.iphmx.com X-Remote-IP: 162.221.158.21 X-Policy: $RELAYED X-IronPort-AV: E=Sophos;i="5.76,415,1592884800"; d="scan'208";a="26619472" From: George Dunlap To: CC: George Dunlap Subject: [PATCH 7/8] Convert resolving-disagreement.md to rst Date: Fri, 11 Sep 2020 13:40:08 +0100 Message-ID: <20200911124009.3760032-8-george.dunlap@citrix.com> X-Mailer: git-send-email 2.25.1 In-Reply-To: <20200911124009.3760032-1-george.dunlap@citrix.com> References: <20200911124009.3760032-1-george.dunlap@citrix.com> MIME-Version: 1.0 X-BeenThere: xen-devel@lists.xenproject.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Xen developer discussion List-Unsubscribe: , List-Post: List-Help: List-Subscribe: , Errors-To: xen-devel-bounces@lists.xenproject.org Sender: "Xen-devel" communication-practice.rst had an incorrect link; it was listed as being in resolving-disagreements.md, but actually it was in code-review-guide. Convert this to a normal cross-reference. Convert titles / sections, lists, quotes, doc references and so on as before. Convert figure as appropriate. Signed-off-by: George Dunlap --- source/code-review-guide.rst | 1 + source/communication-practice.rst | 6 +- source/index.rst | 1 + ...greement.md => resolving-disagreement.rst} | 109 +++++++++++------- 4 files changed, 71 insertions(+), 46 deletions(-) rename source/{resolving-disagreement.md => resolving-disagreement.rst} (72%) diff --git a/source/code-review-guide.rst b/source/code-review-guide.rst index 9c0040e..5a046a2 100644 --- a/source/code-review-guide.rst +++ b/source/code-review-guide.rst @@ -276,6 +276,7 @@ thread onto a code-base. Different people use different techniques from using addressed * A combination of the above +.. _code-review-problematic-patch-review: .. _problems: Problematic Patch Reviews diff --git a/source/communication-practice.rst b/source/communication-practice.rst index 3ccc087..70f5b8c 100644 --- a/source/communication-practice.rst +++ b/source/communication-practice.rst @@ -385,7 +385,8 @@ A pragmatic approach would be to style and minor issues in the review, until the significant flaw is addressed This saves both the patch author and reviewer(s) time. Note that some -background is covered in detail in `Problematic Patch Reviews <4_>`_. +background is covered in detail in +:ref:`Problematic Patch Reviews `. Reviewers: Welcome newcomers @@ -457,6 +458,8 @@ This section contains common communication issues and provides suggestions on how to avoid them and resolve them. These are **general** issues which affect **all** online communication. As such, we can only try and do our best. +.. _communication-practice-misunderstandings: + Misunderstandings ----------------- @@ -569,7 +572,6 @@ how to avoid and resolve issues. .. _1: https://youtu.be/ehZvBmrLRwg?t=834 .. _2: https://en.wikipedia.org/wiki/Foot_binding .. _3: https://xenproject.org/developers/governance/#expressingopinion -.. _4: resolving-disagreement.md#problems .. _5: https://www.wired.com/2006/02/the-secret-cause-of-flame-wars/ .. _6: https://xenproject.org/help/irc/ .. _8: https://en.wikipedia.org/wiki/Erin_Meyer diff --git a/source/index.rst b/source/index.rst index be162cf..c8b45d8 100644 --- a/source/index.rst +++ b/source/index.rst @@ -14,6 +14,7 @@ Welcome to XenProject Governance's documentation! communication-guide code-review-guide communication-practice + resolving-disagreement Indices and tables ================== diff --git a/source/resolving-disagreement.md b/source/resolving-disagreement.rst similarity index 72% rename from source/resolving-disagreement.md rename to source/resolving-disagreement.rst index a635352..28071cf 100644 --- a/source/resolving-disagreement.md +++ b/source/resolving-disagreement.rst @@ -1,51 +1,62 @@ -# Resolving Disagreement +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 +Theory: Paul Graham's hierarchy of disagreement +=============================================== Paul Graham proposed a **disagreement hierarchy** in a 2008 essay -**[How to Disagree][1]**, putting types of arguments into a seven-point +`How to Disagree <1_>`_, putting types 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, as the highest forms of disagreement are rarer. -| ![Graham's Hierarchy of Disagreement][2] | -| *A representation of Graham's hierarchy of disagreement from [Loudacris][3] - modified by [Rocket000][4]* | +.. figure:: https://upload.wikimedia.org/wikipedia/commons/a/a3/Graham%27s_Hierarchy_of_Disagreement-en.svg + :alt: Graham's Hierarchy of Disagreement + + A representation of Graham's hierarchy of disagreement from `Loudacris <3_>`_ + modified by `Rocket000 <4_>`_ In the context of the Xen Project we strive to **only use the top half** of the hierarchy. **Name-calling** and **Ad hominem** arguments are not acceptable within the Xen Project. -## Issue: Scope creep +Issue: Scope creep +================== One thing which occasionally happens during code review is that a code reviewer asks or appears to ask the author of a patch to implement additional functionalities. This could take for example the form of -> Do you think it would be useful for the code to do XXX? -> I can imagine a user wanting to do YYY (and XXX would enable this) + + *Do you think it would be useful for the code to do XXX?* + + *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 request 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 reviewer. To resolve this, it is advisable to + * Report your findings * And then check whether this was merely an interesting suggestion, or something 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 implemented * The **author and reviewer agree** that it may make sense to defer implementation @@ -54,13 +65,16 @@ In the latter case, there are typically several common outcomes 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? + + *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 get an independent opinion from another maintainer or the project's leadership team. -## Issue: [Bikeshedding][5] +Issue: `Bikeshedding <5_>`_ +=========================== Occasionally discussions about unimportant but easy-to-grasp issues can lead to prolonged and unproductive discussions. The best way to approach this is to @@ -73,13 +87,15 @@ review, as you will very quickly get different reviewers providing differing opinions. In this case it is best for the author or a reviewer to call out the potential bikeshedding issue using something like -> Looks we have a bikeshedding issue here -> I think we should call a quick vote to settle the issue + *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][6] or -[lazy voting][7] which lend themselves well to resolve such issues. +Our governance provides the mechanisms of `informal votes <6_>`_ or +`lazy voting <7_>`_ which lend themselves well to resolve such issues. -## Issue: Small functional issues +Issue: Small functional issues +============================== The most common area of disagreements which happen in code reviews, are differing opinions on whether small functional issues in a patch series have to @@ -92,6 +108,7 @@ To explain this better, I am going to use the analogy of some building work that has been performed at your house. Let's say that you have a new bathroom installed. Before paying your builder the last installment, you perform an inspection and you find issues such as + * The seals around the bathtub are not perfectly even * When you open the tap, the plumbing initially makes some loud noise * The shower mixer has been installed the wrong way around @@ -106,13 +123,14 @@ whether your builder had committed 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 **identify** a disagreement as such early and then call it out. Tips on how to -do this, can be found [here][8]. +do this, can be found :doc:`here `. 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 environment this is the most likely outcome, but in open source communities additional concerns have to be considered. + * Code reviewers frequently have been in this situation before with the most 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 @@ -133,7 +151,8 @@ the end of the day, the solution should focus on what is best for the community, which may mean asking for an independent opinion as outlined in the next section. -## Issue: Multiple ways to solve a problem +Issue: Multiple ways to solve a problem +======================================= Frequently it is possible that a problem can be solved in multiple ways and it is not always obvious which one is best. Code reviewers tend to follow their @@ -146,43 +165,45 @@ even if they could be considered style issues, trusting the experience of the code reviewer. Similarly, we ask code reviewers to let the contributor have the freedom of implementation choices, where they do not have a downside. -We do not always succeed in this, as such it is important to **identify** such a -situation and then call it out as outlined [here][8]. +We do not always succeed in this, as such it is important to +**identify** such a situation and then call it out as outlined +:ref:`here `. -## Resolution: Asking for an independent opinion +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, which 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][9] +mediation@xenproject.org to get advice. See our :doc:`Communication Guide ` for more information. -## Decision making and conflict resolution in our governance +Decision making and conflict resolution in our governance +========================================================= -Our [governance][A] contains several proven mechanisms to help with decision +Our `governance `_ contains several proven mechanisms to help with decision making and conflict resolution. See -* [Expressing agreement and disagreement][B] -* [Lazy consensus / Lazy voting][7] -* [Informal votes or surveys][6] -* [Leadership team decisions][C] -* [Conflict resolution][D] - -[1]: http://www.paulgraham.com/disagree.html -[2]: https://upload.wikimedia.org/wikipedia/commons/a/a3/Graham%27s_Hierarchy_of_Disagreement-en.svg -[3]: https://www.createdebate.com/user/viewprofile/Loudacris -[4]: https://en.wikipedia.org/wiki/User:Rocket000 -[5]: https://en.wiktionary.org/wiki/bikeshedding -[6]: https://xenproject.org/developers/governance/#informal-votes-or-surveys -[7]: https://xenproject.org/developers/governance/#lazyconsensus -[8]: communication-practice.md#Misunderstandings -[9]: communication-guide.md -[A]: https://xenproject.org/developers/governance/#decisions -[B]: https://xenproject.org/developers/governance/#expressingopinion -[C]: https://xenproject.org/developers/governance/#leadership -[D]: https://xenproject.org/developers/governance/#conflict + +* `Expressing agreement and disagreement `_ +* `Lazy consensus / Lazy voting <7_>`_ +* `Informal votes or surveys <6_>`_ +* `Leadership team decisions `_ +* `Conflict resolution `_ + +.. _1: http://www.paulgraham.com/disagree.html +.. _3: https://www.createdebate.com/user/viewprofile/Loudacris +.. _4: https://en.wikipedia.org/wiki/User:Rocket000 +.. _5: https://en.wiktionary.org/wiki/bikeshedding +.. _6: https://xenproject.org/developers/governance/#informal-votes-or-surveys +.. _7: https://xenproject.org/developers/governance/#lazyconsensus +.. _A: https://xenproject.org/developers/governance/#decisions +.. _B: https://xenproject.org/developers/governance/#expressingopinion +.. _C: https://xenproject.org/developers/governance/#leadership +.. _D: https://xenproject.org/developers/governance/#conflict From patchwork Fri Sep 11 12:40:09 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: George Dunlap X-Patchwork-Id: 11770461 Return-Path: Received: from mail.kernel.org (pdx-korg-mail-1.web.codeaurora.org [172.30.200.123]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id DE02D92C for ; Fri, 11 Sep 2020 12:42:04 +0000 (UTC) Received: from lists.xenproject.org (lists.xenproject.org [192.237.175.120]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPS id A2E4E206DB for ; Fri, 11 Sep 2020 12:42:04 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=fail reason="signature verification failed" (1024-bit key) header.d=citrix.com header.i=@citrix.com header.b="X+rKW6S/" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org A2E4E206DB Authentication-Results: mail.kernel.org; dmarc=fail (p=reject dis=none) header.from=citrix.com Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=xen-devel-bounces@lists.xenproject.org Received: from localhost ([127.0.0.1] helo=lists.xenproject.org) by lists.xenproject.org with esmtp (Exim 4.92) (envelope-from ) id 1kGiLw-0006gL-AA; Fri, 11 Sep 2020 12:40:32 +0000 Received: from us1-rack-iad1.inumbo.com ([172.99.69.81]) by lists.xenproject.org with esmtp (Exim 4.92) (envelope-from ) id 1kGiLv-0006fc-3M for xen-devel@lists.xenproject.org; Fri, 11 Sep 2020 12:40:31 +0000 X-Inumbo-ID: f28dd61f-9d27-45fb-ae9b-b0e0d187e4c1 Received: from esa2.hc3370-68.iphmx.com (unknown [216.71.145.153]) by us1-rack-iad1.inumbo.com (Halon) with ESMTPS id f28dd61f-9d27-45fb-ae9b-b0e0d187e4c1; Fri, 11 Sep 2020 12:40:29 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=simple/simple; d=citrix.com; s=securemail; t=1599828030; h=from:to:cc:subject:date:message-id:in-reply-to: references:mime-version:content-transfer-encoding; bh=2vtEDHW6LGAocMGYC7G5FyGDCoa3gvEx5lWvLZZsoz0=; b=X+rKW6S/PH8ff+iDkz6M1foyPBTLhpTL3gyxJl2Ps2IXa7NKMQTU3I/8 StcH9O/nEFCsWtL0ttA9EHSNGR5IxXo7kPBm62oY+vHFGe3jnVJSXXGSY WWtA/CLsDScIjlE8eMXmVltNgLNoXE8iRhI/hOzYANarK5ETyBRF3ftBC A=; Authentication-Results: esa2.hc3370-68.iphmx.com; dkim=none (message not signed) header.i=none IronPort-SDR: mp7M4Ck9v/m0/QPCNBdgw46gEHlCY2pRLrxIgHXyvZ+plo0AMfAQjxFjXlzsopLpM2oZgCYm8n rBb9ZbckW+JRvqUi1IOzDJnDqaUT9tUwBpb43z9bVrs4wSwsIC3uLxNeJ2xMjCWXegubXeM30y 7UTq/4eoV8S+JxGCeXIGj6uK6wBEwYvpoqtv5Xp+MI9gI+ZPdX8A8UJN8KhpqAg445uqARaE4u Qw+J0CucH9QI1IgS7tA36qJi7PZQKDYQyp7mhb+lZtpcxZrLnuAqKzsDHZTLP6ZZPI6vqmfnFC ddg= X-SBRS: 2.7 X-MesageID: 26497501 X-Ironport-Server: esa2.hc3370-68.iphmx.com X-Remote-IP: 162.221.158.21 X-Policy: $RELAYED X-IronPort-AV: E=Sophos;i="5.76,415,1592884800"; d="scan'208";a="26497501" From: George Dunlap To: CC: George Dunlap Subject: [PATCH 8/8] Clean up index page Date: Fri, 11 Sep 2020 13:40:09 +0100 Message-ID: <20200911124009.3760032-9-george.dunlap@citrix.com> X-Mailer: git-send-email 2.25.1 In-Reply-To: <20200911124009.3760032-1-george.dunlap@citrix.com> References: <20200911124009.3760032-1-george.dunlap@citrix.com> MIME-Version: 1.0 X-BeenThere: xen-devel@lists.xenproject.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Xen developer discussion List-Unsubscribe: , List-Post: List-Help: List-Subscribe: , Errors-To: xen-devel-bounces@lists.xenproject.org Sender: "Xen-devel" Get rid of "change this here" comments. Break into two sections: "Regulations", which are rules, and "Guides", which are suggestions. Remove unused indexes. Signed-off-by: George Dunlap --- source/index.rst | 26 +++++++++++++++++++------- 1 file changed, 19 insertions(+), 7 deletions(-) diff --git a/source/index.rst b/source/index.rst index c8b45d8..41f92fb 100644 --- a/source/index.rst +++ b/source/index.rst @@ -1,16 +1,26 @@ .. XenProject Governance documentation master file, created by sphinx-quickstart on Tue Sep 8 12:10:02 2020. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. -Welcome to XenProject Governance's documentation! -================================================= +Welcome to XenProject's Governance Documents +============================================ + +The Regulations section contains documents +that regulate the operation of the XenProject, +including minimum acceptable behavior +and possible responses to unacceptable behavior. +The Guides section contains documents describing ideal behavior +that we strive for as a community. .. toctree:: :maxdepth: 2 - :caption: Contents: + :caption: Regulations: code-of-conduct + +.. toctree:: + :maxdepth: 2 + :caption: Guides: + communication-guide code-review-guide communication-practice @@ -19,6 +29,8 @@ Welcome to XenProject Governance's documentation! Indices and tables ================== -* :ref:`genindex` -* :ref:`modindex` +.. Comment out the index for now, but leave it here so we can think + about adding it back in later + * :ref:`genindex` + * :ref:`search`