From nobody Tue May 21 20:00:50 2024 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=redhat.com Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1634634409978329.74678405990255; Tue, 19 Oct 2021 02:06:49 -0700 (PDT) Received: from localhost ([::1]:55510 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mcl56-0003L0-JE for importer@patchew.org; Tue, 19 Oct 2021 05:06:48 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:50658) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mcl2a-0000vO-1D for qemu-devel@nongnu.org; Tue, 19 Oct 2021 05:04:12 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.129.124]:39685) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mcl2U-0006Q1-IS for qemu-devel@nongnu.org; Tue, 19 Oct 2021 05:04:11 -0400 Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-31-8R_HAFycO6C0SgX2GkYkAg-1; Tue, 19 Oct 2021 05:04:01 -0400 Received: from smtp.corp.redhat.com (int-mx03.intmail.prod.int.phx2.redhat.com [10.5.11.13]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id ECF9F80A5D1; Tue, 19 Oct 2021 09:03:59 +0000 (UTC) Received: from paraplu.home (unknown [10.39.194.235]) by smtp.corp.redhat.com (Postfix) with ESMTP id 133EF5BB0D; Tue, 19 Oct 2021 09:03:56 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1634634245; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=oYgtW/iEns3JGfHcerWX8mSqSLvcypj5tNp+7meJktQ=; b=AOeo3hb7fC95UBVB94x+Xnd1opScaxdVe3feerDVpSURRuinFX0PSSpN4MtWe4GcztcaSF GIUF8Wf/+Rru0BBQ/m1zEVjgnxhIALpHOGJxR3eGn8Tj1V88fsqUs1zBJpgKykEwyYv3W6 U7hKdxHwa8Oc/Rd2wRPMIyEGeeNSXTw= X-MC-Unique: 8R_HAFycO6C0SgX2GkYkAg-1 From: Kashyap Chamarthy To: qemu-devel@nongnu.org Subject: [PATCH v2 1/6] docs: rSTify the "TrivialPatches" wiki Date: Tue, 19 Oct 2021 11:03:39 +0200 Message-Id: <20211019090344.3054300-2-kchamart@redhat.com> In-Reply-To: <20211019090344.3054300-1-kchamart@redhat.com> References: <20211019090344.3054300-1-kchamart@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.13 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=kchamart@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=170.10.129.124; envelope-from=kchamart@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -8 X-Spam_score: -0.9 X-Spam_bar: / X-Spam_report: (-0.9 / 5.0 requ) DKIMWL_WL_HIGH=-0.049, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_LOW=-0.7, RCVD_IN_MSPIKE_H4=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=unavailable autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Peter Maydell , Thomas Huth , Kashyap Chamarthy , qemu-trivial@nongnu.org, Eric Blake , Michael Tokarev , Laurent Vivier , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Stefan Hajnoczi , Paolo Bonzini , John Snow Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) X-ZM-MESSAGEID: 1634634413201100005 Content-Type: text/plain; charset="utf-8" The original wiki is here[1]. I converted by copying the wiki source into a .wiki file and convert to rST using `pandoc`: $ pandoc -f Mediawiki -t rst trivial-patches.wiki -o trivial-patche= s.rst Update the active maintainer names to reflect current reality. [1] https://wiki.qemu.org/Contribute/TrivialPatches Signed-off-by: Kashyap Chamarthy --- I've only retained Laurent's name as per Philip's review here: https://lists.nongnu.org/archive/html/qemu-devel/2021-09/msg05624.html --- docs/devel/trivial-patches.rst | 51 ++++++++++++++++++++++++++++++++++ 1 file changed, 51 insertions(+) create mode 100644 docs/devel/trivial-patches.rst diff --git a/docs/devel/trivial-patches.rst b/docs/devel/trivial-patches.rst new file mode 100644 index 0000000000..7df0f901f5 --- /dev/null +++ b/docs/devel/trivial-patches.rst @@ -0,0 +1,51 @@ +Trivial Patches +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +Overview +-------- + +Trivial patches that change just a few lines of code sometimes languish +on the mailing list even though they require only a small amount of +review. This is often the case for patches that do not fall under an +actively maintained subsystem and therefore fall through the cracks. + +The trivial patches team take on the task of reviewing and building pull +requests for patches that: + +- Do not fall under an actively maintained subsystem. +- Are single patches or short series (max 2-4 patches). +- Only touch a few lines of code. + +**You should hint that your patch is a candidate by CCing +qemu-trivial@nongnu.org.** + +Repositories +------------ + +Since the trivial patch team rotates maintainership there is only one +active repository at a time: + +- git://git.corpit.ru/qemu.git trivial-patches - `browse `__ +- git://github.com/vivier/qemu.git trivial-patches - `browse `__ + +Workflow +-------- + +The trivial patches team rotates the duty of collecting trivial patches +amongst its members. A team member's job is to: + +1. Identify trivial patches on the development mailing list. +2. Review trivial patches, merge them into a git tree, and reply to state + that the patch is queued. +3. Send pull requests to the development mailing list once a week. + +A single team member can be on duty as long as they like. The suggested +time is 1 week before handing off to the next member. + +Team +---- + +If you would like to join the trivial patches team, contact Laurent +Vivier. The current team includes: + +- `Laurent Vivier `__ --=20 2.31.1 From nobody Tue May 21 20:00:50 2024 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=redhat.com Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 16346344086991002.8876074054409; Tue, 19 Oct 2021 02:06:48 -0700 (PDT) Received: from localhost ([::1]:55420 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mcl55-0003Hk-E1 for importer@patchew.org; Tue, 19 Oct 2021 05:06:47 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:50656) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mcl2Z-0000v7-Rw for qemu-devel@nongnu.org; Tue, 19 Oct 2021 05:04:11 -0400 Received: from us-smtp-delivery-124.mimecast.com ([216.205.24.124]:20021) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mcl2X-0006Ve-AG for qemu-devel@nongnu.org; Tue, 19 Oct 2021 05:04:11 -0400 Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-153-54r5FwCjN7OUXfT7cEEstQ-1; Tue, 19 Oct 2021 05:04:04 -0400 Received: from smtp.corp.redhat.com (int-mx03.intmail.prod.int.phx2.redhat.com [10.5.11.13]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 0DD211006AAA; Tue, 19 Oct 2021 09:04:03 +0000 (UTC) Received: from paraplu.home (unknown [10.39.194.235]) by smtp.corp.redhat.com (Postfix) with ESMTP id 56E6970951; Tue, 19 Oct 2021 09:04:00 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1634634247; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=4nv7AXTh09QGlEnyMGAR5DJ9aoGOvs7/rWd9h2sq6p4=; b=anNItmUR50+n360WJttSlRXzC/jD4xxRjoDsHpe2hp5Zfz9HrDK43fo4dMmmusghRNca90 Pd2MFX/ljJlhgf633kodKbqvF5p27tt+k7kwJqkYH85zgSYyWfRcus+Gc5RVvRYFtpTWDc o3mt/gpLZrFCMegaf2LBYjtFaXK37Dw= X-MC-Unique: 54r5FwCjN7OUXfT7cEEstQ-1 From: Kashyap Chamarthy To: qemu-devel@nongnu.org Subject: [PATCH v2 2/6] docs: rSTify the "SpellCheck" wiki Date: Tue, 19 Oct 2021 11:03:40 +0200 Message-Id: <20211019090344.3054300-3-kchamart@redhat.com> In-Reply-To: <20211019090344.3054300-1-kchamart@redhat.com> References: <20211019090344.3054300-1-kchamart@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.13 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=kchamart@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=216.205.24.124; envelope-from=kchamart@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -28 X-Spam_score: -2.9 X-Spam_bar: -- X-Spam_report: (-2.9 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.049, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_LOW=-0.7, RCVD_IN_MSPIKE_H2=-0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Peter Maydell , Thomas Huth , Kashyap Chamarthy , qemu-trivial@nongnu.org, Eric Blake , Michael Tokarev , Laurent Vivier , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Stefan Hajnoczi , Paolo Bonzini , John Snow Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) X-ZM-MESSAGEID: 1634634409857100001 Content-Type: text/plain; charset="utf-8" The original wiki is here[1]. I converted by copying the wiki source into a .wiki file and convert to rST using `pandoc`: $ pandoc -f Mediawiki -t rst spell-check.wiki -o spell-check.rst As part of this rST converstion, I've removed the dated and `codespell` invocations, and linked to the GitHub repo. And cleaned up a couple of external URLs. [1] https://wiki.qemu.org/Contribute/SpellCheck Signed-off-by: Kashyap Chamarthy Reviewed-by: Philippe Mathieu-Daud=C3=A9 --- docs/devel/spell-check.rst | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) create mode 100644 docs/devel/spell-check.rst diff --git a/docs/devel/spell-check.rst b/docs/devel/spell-check.rst new file mode 100644 index 0000000000..61275b73c2 --- /dev/null +++ b/docs/devel/spell-check.rst @@ -0,0 +1,20 @@ +Spell Check +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +QEMU uses British or American English in code and documentation. There +are some typical spelling bugs which can be easily avoided by using +tools like ``codespell``. + +`codespell `__ is a +Python script which detects (and optionally fixes) the most common +spelling bugs. It is packaged for most common Linux distributions. + +.. _external_links: + +External Links +-------------- + +- A spell-check tool for Emacs users: + https://github.com/stsquad/my-emacs-stuff/blob/master/my-spell.el +- http://en.wikipedia.org/wiki/Wikipedia:Lists_of_common_misspellings/For_= machines +- http://grammar.yourdictionary.com/spelling-and-word-lists/misspelled.html --=20 2.31.1 From nobody Tue May 21 20:00:50 2024 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=redhat.com Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1634634578305925.5368158121893; Tue, 19 Oct 2021 02:09:38 -0700 (PDT) Received: from localhost ([::1]:34514 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mcl7p-00088Y-1f for importer@patchew.org; Tue, 19 Oct 2021 05:09:37 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:50750) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mcl2k-00014a-Fq for qemu-devel@nongnu.org; Tue, 19 Oct 2021 05:04:23 -0400 Received: from us-smtp-delivery-124.mimecast.com ([216.205.24.124]:54775) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mcl2f-0007BW-SU for qemu-devel@nongnu.org; Tue, 19 Oct 2021 05:04:21 -0400 Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-421-zF4cbfO6PjGq4HfqN6Lfxw-1; Tue, 19 Oct 2021 05:04:07 -0400 Received: from smtp.corp.redhat.com (int-mx03.intmail.prod.int.phx2.redhat.com [10.5.11.13]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 4B82F18125C6; Tue, 19 Oct 2021 09:04:06 +0000 (UTC) Received: from paraplu.home (unknown [10.39.194.235]) by smtp.corp.redhat.com (Postfix) with ESMTP id 53D347092E; Tue, 19 Oct 2021 09:04:03 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1634634256; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=AOGm4vK+NE9UAvOpm9xDnOyNCpUTjIP9TRU6et7ywjc=; b=hjmU34+JU8VyMB37GPKNJ6RhWMgG7iKFcEQLtMnLXMtjo8U4gTpE3Ua7Rqsz+3gqcfvhCa uCuzlj+DXVJD/o9eG3QvIvCn52VM1NQPL4nQjCY86x9j/4TA3vcQmnyGBy/WiKEZk0NMiq 7CoK28gIC4CyL8xFOPtXYrPlU6QFs38= X-MC-Unique: zF4cbfO6PjGq4HfqN6Lfxw-1 From: Kashyap Chamarthy To: qemu-devel@nongnu.org Subject: [PATCH v2 3/6] docs: rSTify the "KeySigningParty" wiki Date: Tue, 19 Oct 2021 11:03:41 +0200 Message-Id: <20211019090344.3054300-4-kchamart@redhat.com> In-Reply-To: <20211019090344.3054300-1-kchamart@redhat.com> References: <20211019090344.3054300-1-kchamart@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.13 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=kchamart@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=216.205.24.124; envelope-from=kchamart@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -8 X-Spam_score: -0.9 X-Spam_bar: / X-Spam_report: (-0.9 / 5.0 requ) DKIMWL_WL_HIGH=-0.049, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_LOW=-0.7, RCVD_IN_MSPIKE_H2=-0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Peter Maydell , Thomas Huth , Kashyap Chamarthy , qemu-trivial@nongnu.org, Eric Blake , Michael Tokarev , Laurent Vivier , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Stefan Hajnoczi , Paolo Bonzini , John Snow Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) X-ZM-MESSAGEID: 1634634579876100001 Content-Type: text/plain; charset="utf-8" The original wiki is here[1]. I converted by copying the wiki source into a .wiki file and convert to rST using `pandoc`: $ pandoc -f Mediawiki -t rst key-signing-party.wiki -o key-signing-party.rst This is a 1-1 conversion; no content changes. [1] https://wiki.qemu.org/KeySigningParty Signed-off-by: Kashyap Chamarthy --- docs/devel/key-signing-party.rst | 171 +++++++++++++++++++++++++++++++ 1 file changed, 171 insertions(+) create mode 100644 docs/devel/key-signing-party.rst diff --git a/docs/devel/key-signing-party.rst b/docs/devel/key-signing-part= y.rst new file mode 100644 index 0000000000..94e133c40e --- /dev/null +++ b/docs/devel/key-signing-party.rst @@ -0,0 +1,171 @@ +Key-signing Party +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +.. _whats_a_key_signing_party: + +What's a key-signing party? +--------------------------- + +A key-signing party is a get-together with PGP users for the purpose of +meeting other PGP users and signing each other's keys. This helps to +extend the "web of trust" to a great degree. Also, it sometimes serves +as a forum to discuss strong cryptography and related issues. In QEMU we +use PGP keys to sign pull requests, so submaintainers need to have PGP +keys signed by those with direct commit access. + +This wiki page gives general information on how we run key-signing +parties for QEMU; usually there will be one at KVM Forum. For details of +a specific event (location, organizer, etc) see the wiki page for that +event. + +The instructions here are pretty specific, because there will likely be +at least a dozen people trying to arrange to sign each others' keys. To +get this done in a reasonable time we need to be efficient about it, so +following the instructions makes it easier and smoother for everyone. If +(for instance) you don't send your key to the organizer before the +deadline then it's quite likely you won't get your key signed. + +.. _what_do_i_need_for_this_party: + +What do I need for this party? +------------------------------ + +.. _required_items: + +Required Items +~~~~~~~~~~~~~~ + +- Physical attendance +- Positive picture ID +- Your Key ID, Key type, HEX fingerprint, and Key size +- A pen/pencil or whatever you'd like to write with.... +- NO computer + +.. _required_process: + +Required Process +~~~~~~~~~~~~~~~~ + +- Generate a key/Remember your pass phrase +- All attendees send their public keys to a public keyserver. Unless + specified otherwise, use keys.gnupg.net. If for some reason you don't + want your key to be in a public keyserver, but still want to + participate, please let me know. +- All attendees send their key ID, key type, fingerprint, and key size + to the host, who will compile everyone's key information. +- The host prints a list with everyone's key ID, key type, fingerprint, + and key size from the compiled keyrings and distributes copies of the + printout at the meeting. +- Attend the party. Bring along a paper copy of your key ID, key type, + fingerprint, and key size that you obtained from your own keyring. + You must also bring along a suitable photo ID. Instruct the attendees + at the beginning that they are to make two marks on the listing, one + for correct key information (key ID, key type, fingerprint, and key + size) and one if the ID check is ok. +- At the meeting each key owner reads his key ID, key type, + fingerprint, key size, and user ID from his own printout, not from + the distributed listing. This is because there could be an error, + intended or not, on the listing. This is also the time to tell which + ID's to sign or not. If the key information matches your printout + then place a check-mark by the key. +- After everyone has read his key ID information, have all attendees + form a line. +- The first person walks down the line having every person check his + ID. +- The second person follows immediately behind the first person and so + on. +- If you are satisfied that the person is who they say they are, and + that the key on the printout is theirs, you place another check-mark + next to their key on your printout. +- Once the first person cycles back around to the front of the line he + has checked all the other IDs and his ID has been checked by all + others. +- After everybody has identified himself or herself the formal part of + the meeting is over. You are free to leave or to stay and discuss + matters of PGP and privacy (or anything else) with fellow PGP users. + If everyone is punctual the formal part of the evening should take + less than an hour. +- After confirming that the key information on the key server matches + the printout that you have checked, sign the appropriate keys. Keys + can only be signed if they have two check-marks. Note that it is + really important to check the full fingerprint -- there are many keys + on the keyservers are maliciously generated fakes which have the same + short 32-bit keyid but the wrong fingerprint! +- Send the signed keys back to the keyservers. +- Use those keys as often as possible. + +.. _why_shouldnt_i_bring_a_computer: + +Why shouldn't I bring a computer? +--------------------------------- + +There are a variety of reasons, why you don't want to do this. The short +answer is it would be insecure, unsafe, and of no benefit. For those not +convinced, here are some reasons why it is insecure, unsafe, and of no +benefit. + +- Someone might have modified the computers programs, operating system, + or hardware to steal or modify keys. +- If people are swapping disks with their keys on them the computer + owner has to worry about viruses. +- If people are carrying their secret keys with them and intend to do + the signing at the actual meeting by typing their passphrase into a + computer, then they are open to key-logging attacks, + shoulder-surfing, etc. +- It is much better to just exchange key details and verify ID and then + do the signing when you get home to your own trusted computer. +- Someone might spill beer on it. +- Someone might drop it or knock it off the table. +- More reasons, I don't feel like articulating + +.. _other_questions_about_signing_keys: + +Other questions about signing keys? +----------------------------------- + +You may want to read the `Keysigning Party +Howto `__ which +includes an explanation of the concepts behind keysigning, instructions +for hosting a keysigning party, instructions for participating in a +keysigning party, and step by step instructions for signing other's +keys. + +If you're looking for quick answers you may want to look to the +questions and answers below, which all come from the `PGP +FAQ `__. It also has a lot +of other good information, besides what is linked to below. + +- `What is key + signing? `= __ +- `How do I sign a + key? `__ +- `Should I sign my own + key? `__ +- `Should I sign X's + key? `__ +- `How do I verify someone's + identity? `__ +- `How do I know someone hasn't sent me a bogus key to + sign? `__ + +.. _other_useful_pgp_links: + +Other useful PGP links +---------------------- + +A few more links for PGP newbies, or those who wish to re acquaint +themselves. + +- http://www.pgpi.org/ -- The International PGP Home Page +- http://www.pgpi.org/download/ -- Download PGP +- http://www.gnupg.org/ -- GNU PGP (Linux) +- http://www.pgpi.org/products/tools/search/ -- PGP Tools, Shells, and + Plugins + +.. _what_if_i_still_have_a_question: + +What if I still have a question? +-------------------------------- + +If you'd like some help answering it, you can contact the event +coordinator. --=20 2.31.1 From nobody Tue May 21 20:00:50 2024 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=redhat.com Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1634634586668118.10517497269518; Tue, 19 Oct 2021 02:09:46 -0700 (PDT) Received: from localhost ([::1]:34822 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mcl7x-0008L7-Mw for importer@patchew.org; Tue, 19 Oct 2021 05:09:45 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:50708) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mcl2g-00013G-5U for qemu-devel@nongnu.org; Tue, 19 Oct 2021 05:04:19 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.133.124]:32854) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mcl2c-0006yK-IF for qemu-devel@nongnu.org; Tue, 19 Oct 2021 05:04:16 -0400 Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-548-pypDYXFMNBiW7mJsY-jCHA-1; Tue, 19 Oct 2021 05:04:10 -0400 Received: from smtp.corp.redhat.com (int-mx03.intmail.prod.int.phx2.redhat.com [10.5.11.13]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 4623380A5C8; Tue, 19 Oct 2021 09:04:09 +0000 (UTC) Received: from paraplu.home (unknown [10.39.194.235]) by smtp.corp.redhat.com (Postfix) with ESMTP id 98DC570951; Tue, 19 Oct 2021 09:04:06 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1634634253; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=TC3q6jkQP7DXrgT7NDpkNU+5AI3iGndsylS945PDy+E=; b=LNmWgW+EH3VPoxh3l+8NzKJ85cdOI7XtKdpsYVxDBlqSml5hKRWCAXzNvs5gmp27mA6ljA T+TtojcPetEDPSgY8hkmCIDrOc3i2X1NdLejy/X7u3HIt8hs1H3lcZllqe+lYzCbgYDmDN 29EpcOKqTf01habM4Xj7j5lRWI75NT0= X-MC-Unique: pypDYXFMNBiW7mJsY-jCHA-1 From: Kashyap Chamarthy To: qemu-devel@nongnu.org Subject: [PATCH v2 4/6] docs: rSTify the "SubmitAPullRequest" wiki Date: Tue, 19 Oct 2021 11:03:42 +0200 Message-Id: <20211019090344.3054300-5-kchamart@redhat.com> In-Reply-To: <20211019090344.3054300-1-kchamart@redhat.com> References: <20211019090344.3054300-1-kchamart@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.13 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=kchamart@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=170.10.133.124; envelope-from=kchamart@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -28 X-Spam_score: -2.9 X-Spam_bar: -- X-Spam_report: (-2.9 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.049, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_LOW=-0.7, RCVD_IN_MSPIKE_H2=-0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Peter Maydell , Thomas Huth , Kashyap Chamarthy , qemu-trivial@nongnu.org, Eric Blake , Michael Tokarev , Laurent Vivier , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Stefan Hajnoczi , Paolo Bonzini , John Snow Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) X-ZM-MESSAGEID: 1634634588440100001 Content-Type: text/plain; charset="utf-8" The original wiki is here[1]. I converted by copying the wiki source into a .wiki file and convert to rST using `pandoc`: $ pandoc -f Mediawiki -t rst submitting-a-pull-request.wiki \ -o submitting-a-pull-request.rst This is a 1-1 conversion; no content changes besides updating the "KeySigningParty" linkt to the rSTified (HTML) page. [1] https://wiki.qemu.org/Contribute/SubmitAPullRequest Signed-off-by: Kashyap Chamarthy Reviewed-by: Philippe Mathieu-Daud=C3=A9 --- docs/devel/submitting-a-pull-request.rst | 79 ++++++++++++++++++++++++ 1 file changed, 79 insertions(+) create mode 100644 docs/devel/submitting-a-pull-request.rst diff --git a/docs/devel/submitting-a-pull-request.rst b/docs/devel/submitti= ng-a-pull-request.rst new file mode 100644 index 0000000000..d2ee84c85a --- /dev/null +++ b/docs/devel/submitting-a-pull-request.rst @@ -0,0 +1,79 @@ +Submit a Pull Request +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +QEMU welcomes contributions of code, but we generally expect these to be +sent as simple patch emails to the mailing list (see our page on +`submitting a patch +`__ +for more details). Generally only existing submaintainers of a tree +will need to submit pull requests, although occasionally for a large +patch series we might ask a submitter to send a pull request. This page +documents our recommendations on pull requests for those people. + +A good rule of thumb is not to send a pull request unless somebody asks +you to. + +**Resend the patches with the pull request** as emails which are +threaded as follow-ups to the pull request itself. The simplest way to +do this is to use ``git format-patch --cover-letter`` to create the +emails, and then edit the cover letter to include the pull request +details that ``git request-pull`` outputs. + +**Use PULL as the subject line tag** in both the cover letter and the +retransmitted patch mails (for example, by using +``--subject-prefix=3DPULL`` in your ``git format-patch`` command). This +helps people to filter in or out the resulting emails (especially useful +if they are only CC'd on one email out of the set). + +**Each patch must have your own Signed-off-by: line** as well as that of +the original author if the patch was not written by you. This is because +with a pull request you're now indicating that the patch has passed via +you rather than directly from the original author. + +**Don't forget to add Reviewed-by: and Acked-by: lines**. When other +people have reviewed the patches you're putting in the pull request, +make sure you've copied their signoffs across. (If you use the `patches +tool `__ to add patches from email +directly to your git repo it will include the tags automatically; if +you're updating patches manually or in some other way you'll need to +edit the commit messages by hand.) + +**Don't send pull requests for code that hasn't passed review**. A pull +request says these patches are ready to go into QEMU now, so they must +have passed the standard code review processes. In particular if you've +corrected issues in one round of code review, you need to send your +fixed patch series as normal to the list; you can't put it in a pull +request until it's gone through. (Extremely trivial fixes may be OK to +just fix in passing, but if in doubt err on the side of not.) + +**Test before sending**. This is an obvious thing to say, but make sure +everything builds (including that it compiles at each step of the patch +series) and that "make check" passes before sending out the pull +request. As a submaintainer you're one of QEMU's lines of defense +against bad code, so double check the details. + +**All pull requests must be signed**. If your key is not already signed +by members of the QEMU community, you should make arrangements to attend +a `KeySigningParty +`__ +(for example at KVM Forum) or make alternative arrangements to have your +key signed by an attendee. Key signing requires meeting another +community member \*in person\* so please make appropriate arrangements. +By "signed" here we mean that the pullreq email should quote a tag which +is a GPG-signed tag (as created with 'gpg tag -s ...'). + +**Pull requests not for master should say "not for master" and have +"PULL SUBSYSTEM whatever" in the subject tag**. If your pull request is +targeting a stable branch or some submaintainer tree, please include the +string "not for master" in the cover letter email, and make sure the +subject tag is "PULL SUBSYSTEM s390/block/whatever" rather than just +"PULL". This allows it to be automatically filtered out of the set of +pull requests that should be applied to master. + +You might be interested in +`https://git.linaro.org/people/peter.maydell/misc-scripts.git/tree/make-pu= llreq +the make-pullreq +script `__, +which automates some of this process for you and includes a few sanity +checks. Note that you must edit it to configure it suitably for your +local situation! --=20 2.31.1 From nobody Tue May 21 20:00:50 2024 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=redhat.com Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1634634757528468.91185455657035; Tue, 19 Oct 2021 02:12:37 -0700 (PDT) Received: from localhost ([::1]:41102 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mclAi-00049z-6i for importer@patchew.org; Tue, 19 Oct 2021 05:12:36 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:50812) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mcl2w-0001CF-CG for qemu-devel@nongnu.org; Tue, 19 Oct 2021 05:04:34 -0400 Received: from us-smtp-delivery-124.mimecast.com ([216.205.24.124]:59043) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mcl2p-0007hk-BB for qemu-devel@nongnu.org; Tue, 19 Oct 2021 05:04:34 -0400 Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-213-yq6Wgl3ePqew2LyVwOkjeQ-1; Tue, 19 Oct 2021 05:04:18 -0400 Received: from smtp.corp.redhat.com (int-mx03.intmail.prod.int.phx2.redhat.com [10.5.11.13]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 2A798800685; Tue, 19 Oct 2021 09:04:17 +0000 (UTC) Received: from paraplu.home (unknown [10.39.194.235]) by smtp.corp.redhat.com (Postfix) with ESMTP id A47EF7092E; Tue, 19 Oct 2021 09:04:09 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1634634265; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=Jw3zlivBVzRs2TlwQxHYykWUvnycjLI/e5k7sUvAXRk=; b=P2bT74yYlfCrjNjMFQgCkj4p4fhsyEL3LdXWEXfPWt7V1LeEh7yWigxq/lG8p800PIaTnt 9dFb4JHpjkx+iA0xwQb6FmFXD0x6kzM4tBH8wZ62JIKZcaG/zu/xjCMY2+RmtBTOCuuXVv iXIcE2WlWsHj4sdewzxNV6Z9iZGOW6I= X-MC-Unique: yq6Wgl3ePqew2LyVwOkjeQ-1 From: Kashyap Chamarthy To: qemu-devel@nongnu.org Subject: [PATCH v2 5/6] docs: rSTify the "SubmitAPatch" wiki Date: Tue, 19 Oct 2021 11:03:43 +0200 Message-Id: <20211019090344.3054300-6-kchamart@redhat.com> In-Reply-To: <20211019090344.3054300-1-kchamart@redhat.com> References: <20211019090344.3054300-1-kchamart@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.13 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=kchamart@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=216.205.24.124; envelope-from=kchamart@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -28 X-Spam_score: -2.9 X-Spam_bar: -- X-Spam_report: (-2.9 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.049, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_LOW=-0.7, RCVD_IN_MSPIKE_H2=-0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Peter Maydell , Thomas Huth , Kashyap Chamarthy , qemu-trivial@nongnu.org, Eric Blake , Michael Tokarev , Laurent Vivier , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Stefan Hajnoczi , Paolo Bonzini , John Snow Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) X-ZM-MESSAGEID: 1634634759366100001 - The original wiki is here[1]. I copied the wiki source[2] into a .wiki file, and used `pandoc` to convert it to rST: $> pandoc -f Mediawiki -t rst submitting-a-patch.wiki -o submitting-a-patch.rst - The only minor touch-ups I did was to fix URLs. But 99%, it is a 1-1 conversion. (An example of a "touch-up": under the section "Patch emails must include a Signed-off-by: line", I updated the "see SubmittingPatches 1.12" to "1.12) Sign your work") - I have also converted a couple other related wiki pages (included in this patch series) that were hyperlinked within the SubmitAPatch page, or a page that it refers to. - SubmitAPullRequest: https://wiki.qemu.org/Contribute/SubmitAPullRequest - KeySigningParty: https://wiki.qemu.org/KeySigningParty - SpellCheck: https://wiki.qemu.org/Contribute/SpellCheck - TrivialPatches: https://wiki.qemu.org/Contribute/TrivialPatches - Over time, many people contributed to this wiki page; you can find all the authors in the wiki history[3]. [1] https://wiki.qemu.org/Contribute/SubmitAPatch [2] http://wiki.qemu.org/index.php?title=3DContribute/SubmitAPatch&action= =3Dedit [3] http://wiki.qemu.org/index.php?title=3DContribute/SubmitAPatch&action= =3Dhistory Signed-off-by: Kashyap Chamarthy --- docs/devel/submitting-a-patch.rst | 460 ++++++++++++++++++++++++++++++ 1 file changed, 460 insertions(+) create mode 100644 docs/devel/submitting-a-patch.rst diff --git a/docs/devel/submitting-a-patch.rst b/docs/devel/submitting-a-pa= tch.rst new file mode 100644 index 0000000000..c1bb30c063 --- /dev/null +++ b/docs/devel/submitting-a-patch.rst @@ -0,0 +1,460 @@ +Submitting a Patch +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D + +QEMU welcomes contributions of code (either fixing bugs or adding new +functionality). However, we get a lot of patches, and so we have some +guidelines about submitting patches. If you follow these, you'll help +make our task of code review easier and your patch is likely to be +committed faster. + +This page seems very long, so if you are only trying to post a quick +one-shot fix, the bare minimum we ask is that: + +- You **must** provide a Signed-off-by: line (this is a hard + requirement because it's how you say "I'm legally okay to contribute + this and happy for it to go into QEMU", modeled after the `Linux + kernel `__ + policy.) ``git commit -s`` or ``git format-patch -s`` will add one. +- All contributions to QEMU must be **sent as patches** to the + qemu-devel `mailing list `__. Patch contributions + should not be posted on the bug tracker, posted on forums, or + externally hosted and linked to. (We have other mailing lists too, + but all patches must go to qemu-devel, possibly with a Cc: to another + list.) ``git send-email`` works best for delivering the patch without + mangling it (`hints for setting it + up `__), + but attachments can be used as a last resort on a first-time + submission. +- You must read replies to your message, and be willing to act on them. + Note, however, that maintainers are often willing to manually fix up + first-time contributions, since there is a learning curve involved in + making an ideal patch submission. + +You do not have to subscribe to post (list policy is to reply-to-all to +preserve CCs and keep non-subscribers in the loop on the threads they +start), although you may find it easier as a subscriber to pick up good +ideas from other posts. If you do subscribe, be prepared for a high +volume of email, often over one thousand messages in a week. The list is +moderated; first-time posts from an email address (whether or not you +subscribed) may be subject to some delay while waiting for a moderator +to whitelist your address. + +The larger your contribution is, or if you plan on becoming a long-term +contributor, then the more important the rest of this page becomes. +Reading the table of contents below should already give you an idea of +the basic requirements. Use the table of contents as a reference, and +read the parts that you have doubts about. + +.. _writing_your_patches: + +Writing your Patches +-------------------- + +.. _use_the_qemu_coding_style: + +Use the QEMU coding style +~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can run run *scripts/checkpatch.pl * before submitting to +check that you are in compliance with our coding standards. Be aware +that ``checkpatch.pl`` is not infallible, though, especially where C +preprocessor macros are involved; use some common sense too. See also: + +- `QEMU Coding Style + `__ + +- `Automate a checkpatch run on + commit `__ + +- `Spell Check + `__ your + patches + +.. _base_patches_against_current_git_master: + +Base patches against current git master +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +There's no point submitting a patch which is based on a released version +of QEMU because development will have moved on from then and it probably +won't even apply to master. We only apply selected bugfixes to release +branches and then only as backports once the code has gone into master. + +.. _split_up_long_patches: + +Split up long patches +~~~~~~~~~~~~~~~~~~~~~ + +Split up longer patches into a patch series of logical code changes. +Each change should compile and execute successfully. For instance, don't +add a file to the makefile in patch one and then add the file itself in +patch two. (This rule is here so that people can later use tools like +```git bisect`` `__ without hitting +points in the commit history where QEMU doesn't work for reasons +unrelated to the bug they're chasing.) Put documentation first, not +last, so that someone reading the series can do a clean-room evaluation +of the documentation, then validate that the code matched the +documentation. A commit message that mentions "Also, ..." is often a +good candidate for splitting into multiple patches. For more thoughts on +properly splitting patches and writing good commit messages, see `this +advice from +OpenStack `__. + +.. _make_code_motion_patches_easy_to_review: + +Make code motion patches easy to review +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If a series requires large blocks of code motion, there are tricks for +making the refactoring easier to review. Split up the series so that +semantic changes (or even function renames) are done in a separate patch +from the raw code motion. Use a one-time setup of +``git config diff.renames true; git config diff.algorithm patience`` +(Refer to `git-config `__.) The +``diff.renames`` property ensures file rename patches will be given in a +more compact representation that focuses only on the differences across +the file rename, instead of showing the entire old file as a deletion +and the new file as an insertion. Meanwhile, the 'diff.algorithm' +property ensures that extracting a non-contiguous subset of one file +into a new file, but where all extracted parts occur in the same order +both before and after the patch, will reduce churn in trying to treat +unrelated ``}`` lines in the original file as separating hunks of +changes. + +Ideally, a code motion patch can be reviewed by doing:: + + git format-patch --stdout -1 > patch; + diff -u <(sed -n 's/^-//p' patch) <(sed -n 's/^\+//p' patch) + +to focus on the few changes that weren't wholesale code motion. + +.. _dont_include_irrelevant_changes: + +Don't include irrelevant changes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In particular, don't include formatting, coding style or whitespace +changes to bits of code that would otherwise not be touched by the +patch. (It's OK to fix coding style issues in the immediate area (few +lines) of the lines you're changing.) If you think a section of code +really does need a reindent or other large-scale style fix, submit this +as a separate patch which makes no semantic changes; don't put it in the +same patch as your bug fix. + +For smaller patches in less frequently changed areas of QEMU, consider +using the `trivial patches process +`__. + +.. _write_a_meaningful_commit_message: + +Write a meaningful commit message +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Commit messages should be meaningful and should stand on their own as a +historical record of why the changes you applied were necessary or +useful. + +QEMU follows the usual standard for git commit messages: the first line +(which becomes the email subject line) is "subsystem: single line +summary of change". Whether the "single line summary of change" starts +with a capital is a matter of taste, but we prefer that the summary does +not end in ".". Look at ``git shortlog -30`` for an idea of sample +subject lines. Then there is a blank line and a more detailed +description of the patch, another blank and your Signed-off-by: line. +Please do not use lines that are longer than 76 characters in your +commit message (so that the text still shows up nicely with "git show" +in a 80-columns terminal window). + +The body of the commit message is a good place to document why your +change is important. Don't include comments like "This is a suggestion +for fixing this bug" (they can go below the "---" line in the email so +they don't go into the final commit message). Make sure the body of the +commit message can be read in isolation even if the reader's mailer +displays the subject line some distance apart (that is, a body that +starts with "... so that" as a continuation of the subject line is +harder to follow). + +.. _submitting_your_patches: + +Submitting your Patches +----------------------- + +.. _cc_the_relevant_maintainer: + +CC the relevant maintainer +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Send patches both to the mailing list and CC the maintainer(s) of the +files you are modifying. look in the MAINTAINERS file to find out who +that is. Also try using scripts/get_maintainer.pl from the repository +for learning the most common committers for the files you touched. + +Example:: + + ~/src/qemu/scripts/get_maintainer.pl=C2=A0-f=C2=A0hw/ide/core.c + +In fact, you can automate this, via a one-time setup of ``git config +sendemail.cccmd 'scripts/get_maintainer.pl --nogit-fallback'`` (Refer to +`git-config `__.) + +.. _do_not_send_as_an_attachment: + +Do not send as an attachment +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Send patches inline so they are easy to reply to with review comments. +Do not put patches in attachments. + +.. _use_git_format_patch: + +Use ``git format-patch`` +~~~~~~~~~~~~~~~~~~~~~~~~ + +Use the right diff format. +`git format-patch `__ will +produce patch emails in the right format (check the documentation to +find out how to drive it). You can then edit the cover letter before +using ``git send-email`` to mail the files to the mailing list. (We +recommend `git send-email `__ +because mail clients often mangle patches by wrapping long lines or +messing up whitespace. Some distributions do not include send-email in a +default install of git; you may need to download additional packages, +such as 'git-email' on Fedora-based systems.) Patch series need a cover +letter, with shallow threading (all patches in the series are +in-reply-to the cover letter, but not to each other); single unrelated +patches do not need a cover letter (but if you do send a cover letter, +use --numbered so the cover and the patch have distinct subject lines). +Patches are easier to find if they start a new top-level thread, rather +than being buried in-reply-to another existing thread. + +.. _patch_emails_must_include_a_signed_off_by_line: + +Patch emails must include a ``Signed-off-by:`` line +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +For more information see `1.12) Sign your work +`__. +This is vital or we will not be able to apply your patch! Please use +your real name to sign a patch (not an alias or acronym). + +If you wrote the patch, make sure your "From:" and "Signed-off-by:" +lines use the same spelling. It's okay if you subscribe or contribute to +the list via more than one address, but using multiple addresses in one +commit just confuses things. If someone else wrote the patch, git will +include a "From:" line in the body of the email (different from your +envelope From:) that will give credit to the correct author; but again, +that author's Signed-off-by: line is mandatory, with the same spelling. + +.. _include_a_meaningful_cover_letter: + +Include a meaningful cover letter +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This usually applies only to a series that includes multiple patches; +the cover letter explains the overall goal of such a series. + +When reviewers don't know your goal at the start of their review, they +may object to early changes that don't make sense until the end of the +series, because they do not have enough context yet at that point of +their review. A series where the goal is unclear also risks a higher +number of review-fix cycles because the reviewers haven't bought into +the idea yet. If the cover letter can explain these points to the +reviewer, the process will be smoother patches will get merged faster. +Make sure your cover letter includes a diffstat of changes made over the +entire series; potential reviewers know what files they are interested +in, and they need an easy way determine if your series touches them. + +.. _use_the_rfc_tag_if_needed: + +Use the RFC tag if needed +~~~~~~~~~~~~~~~~~~~~~~~~~ + +For example, "[PATCH RFC v2]". ``git format-patch --subject-prefix=3DRFC`` +can help. + +"RFC" means "Request For Comments" and is a statement that you don't +intend for your patchset to be applied to master, but would like some +review on it anyway. Reasons for doing this include: + +- the patch depends on some pending kernel changes which haven't yet + been accepted, so the QEMU patch series is blocked until that + dependency has been dealt with, but is worth reviewing anyway +- the patch set is not finished yet (perhaps it doesn't cover all use + cases or work with all targets) but you want early review of a major + API change or design structure before continuing + +In general, since it's asking other people to do review work on a +patchset that the submitter themselves is saying shouldn't be applied, +it's best to: + +- use it sparingly +- in the cover letter, be clear about why a patch is an RFC, what areas + of the patchset you're looking for review on, and why reviewers + should care + +.. _participating_in_code_review: + +Participating in Code Review +---------------------------- + +All patches submitted to the QEMU project go through a code review +process before they are accepted. Some areas of code that are well +maintained may review patches quickly, lesser-loved areas of code may +have a longer delay. + +.. _stay_around_to_fix_problems_raised_in_code_review: + +Stay around to fix problems raised in code review +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Not many patches get into QEMU straight away -- it is quite common that +developers will identify bugs, or suggest a cleaner approach, or even +just point out code style issues or commit message typos. You'll need to +respond to these, and then send a second version of your patches with +the issues fixed. This takes a little time and effort on your part, but +if you don't do it then your changes will never get into QEMU. It's also +just polite -- it is quite disheartening for a developer to spend time +reviewing your code and suggesting improvements, only to find that +you're not going to do anything further and it was all wasted effort. + +When replying to comments on your patches **reply to all and not just +the sender** -- keeping discussion on the mailing list means everybody +can follow it. + +.. _pay_attention_to_review_comments: + +Pay attention to review comments +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Someone took their time to review your work, and it pays to respect that +effort; repeatedly submitting a series without addressing all comments +from the previous round tends to alienate reviewers and stall your +patch. Reviewers aren't always perfect, so it is okay if you want to +argue that your code was correct in the first place instead of blindly +doing everything the reviewer asked. On the other hand, if someone +pointed out a potential issue during review, then even if your code +turns out to be correct, it's probably a sign that you should improve +your commit message and/or comments in the code explaining why the code +is correct. + +If you fix issues that are raised during review **resend the entire +patch series** not just the one patch that was changed. This allows +maintainers to easily apply the fixed series without having to manually +identify which patches are relevant. Send the new version as a complete +fresh email or series of emails -- don't try to make it a followup to +version 1. (This helps automatic patch email handling tools distinguish +between v1 and v2 emails.) + +.. _when_resending_patches_add_a_version_tag: + +When resending patches add a version tag +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +All patches beyond the first version should include a version tag -- for +example, "[PATCH v2]". This means people can easily identify whether +they're looking at the most recent version. (The first version of a +patch need not say "v1", just [PATCH] is sufficient.) For patch series, +the version applies to the whole series -- even if you only change one +patch, you resend the entire series and mark it as "v2". Don't try to +track versions of different patches in the series separately. `git +format-patch `__ and `git +send-email `__ both understand +the ``-v2`` option to make this easier. Send each new revision as a new +top-level thread, rather than burying it in-reply-to an earlier +revision, as many reviewers are not looking inside deep threads for new +patches. + +.. _include_version_history_in_patchset_revisions: + +Include version history in patchset revisions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +For later versions of patches, include a summary of changes from +previous versions, but not in the commit message itself. In an email +formatted as a git patch, the commit message is the part above the "---" +line, and this will go into the git changelog when the patch is +committed. This part should be a self-contained description of what this +version of the patch does, written to make sense to anybody who comes +back to look at this commit in git in six months' time. The part below +the "---" line and above the patch proper (git format-patch puts the +diffstat here) is a good place to put remarks for people reading the +patch email, and this is where the "changes since previous version" +summary belongs. The +`git-publish `__ script can +help with tracking a good summary across versions. Also, the +`git-backport-diff `__ script +can help focus reviewers on what changed between revisions. + +.. _tips_and_tricks: + +Tips and Tricks +--------------- + +.. _proper_use_of_reviewed_by_tags_can_aid_review: + +Proper use of Reviewed-by: tags can aid review +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When reviewing a large series, a reviewer can reply to some of the +patches with a Reviewed-by tag, stating that they are happy with that +patch in isolation (sometimes conditional on minor cleanup, like fixing +whitespace, that doesn't affect code content). You should then update +those commit messages by hand to include the Reviewed-by tag, so that in +the next revision, reviewers can spot which patches were already clean +from the previous round. Conversely, if you significantly modify a patch +that was previously reviewed, remove the reviewed-by tag out of the +commit message, as well as listing the changes from the previous +version, to make it easier to focus a reviewer's attention to your +changes. + +.. _if_your_patch_seems_to_have_been_ignored: + +If your patch seems to have been ignored +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If your patchset has received no replies you should "ping" it after a +week or two, by sending an email as a reply-to-all to the patch mail, +including the word "ping" and ideally also a link to the page for the +patch on +`patchwork `__ or +GMANE. It's worth double-checking for reasons why your patch might have +been ignored (forgot to CC the maintainer? annoyed people by failing to +respond to review comments on an earlier version?), but often for +less-maintained areas of QEMU patches do just slip through the cracks. +If your ping is also ignored, ping again after another week or so. As +the submitter, you are the person with the most motivation to get your +patch applied, so you have to be persistent. + +.. _is_my_patch_in: + +Is my patch in? +~~~~~~~~~~~~~~~ + +Once your patch has had enough review on list, the maintainer for that +area of code will send notification to the list that they are including +your patch in a particular staging branch. Periodically, the maintainer +then sends a `pull request += `__ +for aggregating topic branches into mainline qemu. Generally, you do not +need to send a pull request unless you have contributed enough patches +to become a maintainer over a particular section of code. Maintainers +may further modify your commit, by resolving simple merge conflicts or +fixing minor typos pointed out during review, but will always add a +Signed-off-by line in addition to yours, indicating that it went through +their tree. Occasionally, the maintainer's pull request may hit more +difficult merge conflicts, where you may be requested to help rebase and +resolve the problems. It may take a couple of weeks between when your +patch first had a positive review to when it finally lands in qemu.git; +release cycle freezes may extend that time even longer. + +.. _return_the_favor: + +Return the favor +~~~~~~~~~~~~~~~~ + +Peer review only works if everyone chips in a bit of review time. If +everyone submitted more patches than they reviewed, we would have a +patch backlog. A good goal is to try to review at least as many patches +from others as what you submit. Don't worry if you don't know the code +base as well as a maintainer; it's perfectly fine to admit when your +review is weak because you are unfamiliar with the code. --=20 2.31.1 From nobody Tue May 21 20:00:50 2024 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=fail; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=redhat.com Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1634634767631181.4410345317832; Tue, 19 Oct 2021 02:12:47 -0700 (PDT) Received: from localhost ([::1]:41730 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mclAs-0004Zh-G4 for importer@patchew.org; Tue, 19 Oct 2021 05:12:46 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]:50782) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mcl2s-00018N-ER for qemu-devel@nongnu.org; Tue, 19 Oct 2021 05:04:31 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.133.124]:56279) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mcl2p-0007gd-Ar for qemu-devel@nongnu.org; Tue, 19 Oct 2021 05:04:30 -0400 Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-8-93k5-areNm2qKQzvjl8BeA-1; Tue, 19 Oct 2021 05:04:21 -0400 Received: from smtp.corp.redhat.com (int-mx03.intmail.prod.int.phx2.redhat.com [10.5.11.13]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 6D5AC18125C4; Tue, 19 Oct 2021 09:04:20 +0000 (UTC) Received: from paraplu.home (unknown [10.39.194.235]) by smtp.corp.redhat.com (Postfix) with ESMTP id 8841E7092E; Tue, 19 Oct 2021 09:04:17 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1634634264; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=JX4we9rVGSwSP4Q6Da9FYxWUAFu6VceQ1S4FfWRjNLY=; b=QIDPTRaNHOqCVnuGzdIBSToR+zSbI7nZXBz9sJ92nA7/flPXrOmEugYEWmOU1oixVy1CwU IbCGBSw1HQCc9BkfJdlCt6tHYVb9NUYswWxfEywd28jz2BaJyJ6SG9a6IWVWWxIZGatMg9 jAIXV75ELNXyOucoarERciNrlj0Qxco= X-MC-Unique: 93k5-areNm2qKQzvjl8BeA-1 From: Kashyap Chamarthy To: qemu-devel@nongnu.org Subject: [PATCH v2 6/6] docs/devel: Update the rST index file Date: Tue, 19 Oct 2021 11:03:44 +0200 Message-Id: <20211019090344.3054300-7-kchamart@redhat.com> In-Reply-To: <20211019090344.3054300-1-kchamart@redhat.com> References: <20211019090344.3054300-1-kchamart@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.13 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=kchamart@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=170.10.133.124; envelope-from=kchamart@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -28 X-Spam_score: -2.9 X-Spam_bar: -- X-Spam_report: (-2.9 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.049, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_LOW=-0.7, RCVD_IN_MSPIKE_H2=-0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=unavailable autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Peter Maydell , Thomas Huth , Kashyap Chamarthy , qemu-trivial@nongnu.org, Eric Blake , Michael Tokarev , Laurent Vivier , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Stefan Hajnoczi , Paolo Bonzini , John Snow Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) X-ZM-MESSAGEID: 1634634768106100001 Content-Type: text/plain; charset="utf-8" Add the entries for contributing-related rSTified wiki docs. Signed-off-by: Kashyap Chamarthy --- docs/devel/index.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/devel/index.rst b/docs/devel/index.rst index f95df10b3e..f7bec644f3 100644 --- a/docs/devel/index.rst +++ b/docs/devel/index.rst @@ -45,3 +45,8 @@ modifying QEMU's source code. vfio-migration qapi-code-gen writing-qmp-commands + trivial-patches + spell-check + key-signing-party + submitting-a-pull-request + submitting-a-patch --=20 2.31.1