From patchwork Fri Aug 11 17:55:23 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Michael Opdenacker X-Patchwork-Id: 28706 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from aws-us-west-2-korg-lkml-1.web.codeaurora.org (localhost.localdomain [127.0.0.1]) by smtp.lore.kernel.org (Postfix) with ESMTP id 804CFC001B0 for ; Fri, 11 Aug 2023 17:55:44 +0000 (UTC) Received: from relay8-d.mail.gandi.net (relay8-d.mail.gandi.net [217.70.183.201]) by mx.groups.io with SMTP id smtpd.web10.49491.1691776538893874929 for ; Fri, 11 Aug 2023 10:55:39 -0700 Authentication-Results: mx.groups.io; dkim=pass header.i=@bootlin.com header.s=gm1 header.b=iXF3yl80; spf=pass (domain: bootlin.com, ip: 217.70.183.201, mailfrom: michael.opdenacker@bootlin.com) Received: by mail.gandi.net (Postfix) with ESMTPSA id A86691BF205; Fri, 11 Aug 2023 17:55:36 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bootlin.com; s=gm1; t=1691776536; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=oMcHl3ZmhHoJhz5q6B5dh9JgcV4WenZ08O2fPtv1D8U=; b=iXF3yl80fc4g1AFB5CH/ybNH7LT4HP60MJM2caZmWX1SRflsacGuUro7BPzT2ISsNz9dq9 cFRvlbs7I6SoYZkPppytrQrII9c4tI+nfFWilCujN3Hchu9kW7puDgv1Uxn3l+ptCR3ikO qDvLqGyO4fyH+zPH73Y4k1fiLu9t6uQGbt3VsRxog9sds2r1+FzRz4g69mNsXZiPpOYbwq sgWR9GLTyfj6lkBma1cDVdS6m5zHxC1/QpSGgj8D+ARR5ggzzLVStRFRyMS5RIqahb0QaJ MWE9w+YjnW+pkG8+ULpYwx1m5Lls/ReI9ZgdZdO6G68ZT9m3kNA++tcNzyS87A== From: michael.opdenacker@bootlin.com To: docs@lists.yoctoproject.org Cc: Michael Opdenacker , Joshua Watt Subject: [PATCH 1/5] contributor guide: call section "Reporting a defect" Date: Fri, 11 Aug 2023 19:55:23 +0200 Message-Id: <20230811175527.1116864-2-michael.opdenacker@bootlin.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20230811175527.1116864-1-michael.opdenacker@bootlin.com> References: <20230811175527.1116864-1-michael.opdenacker@bootlin.com> MIME-Version: 1.0 X-GND-Sasl: michael.opdenacker@bootlin.com List-Id: X-Webhook-Received: from li982-79.members.linode.com [45.33.32.79] by aws-us-west-2-korg-lkml-1.web.codeaurora.org with HTTPS for ; Fri, 11 Aug 2023 17:55:44 -0000 X-Groupsio-URL: https://lists.yoctoproject.org/g/docs/message/4146 From: Michael Opdenacker Instead of "Submitting a defect". We all write bugs, and nobody needs documentation support for doing so! Signed-off-by: Michael Opdenacker Reported-by: Joshua Watt --- documentation/contributor-guide/index.rst | 2 +- .../contributor-guide/{submit-defect.rst => report-defect.rst} | 2 +- documentation/dev-manual/debugging.rst | 2 +- documentation/ref-manual/resources.rst | 2 +- documentation/ref-manual/system-requirements.rst | 2 +- 5 files changed, 5 insertions(+), 5 deletions(-) rename documentation/contributor-guide/{submit-defect.rst => report-defect.rst} (98%) diff --git a/documentation/contributor-guide/index.rst b/documentation/contributor-guide/index.rst index 7a39f994e2..8fa65045a3 100644 --- a/documentation/contributor-guide/index.rst +++ b/documentation/contributor-guide/index.rst @@ -19,7 +19,7 @@ this. :numbered: identify-component - submit-defect + report-defect recipe-style-guide submit-change diff --git a/documentation/contributor-guide/submit-defect.rst b/documentation/contributor-guide/report-defect.rst similarity index 98% rename from documentation/contributor-guide/submit-defect.rst rename to documentation/contributor-guide/report-defect.rst index 527ffb2dc0..8ef133b842 100644 --- a/documentation/contributor-guide/submit-defect.rst +++ b/documentation/contributor-guide/report-defect.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-2.0-UK -Submitting a Defect Against the Yocto Project and OpenEmbedded +Reporting a Defect Against the Yocto Project and OpenEmbedded ************************************************************** You can use the Yocto Project instance of diff --git a/documentation/dev-manual/debugging.rst b/documentation/dev-manual/debugging.rst index 3a8d5080ce..890578cc05 100644 --- a/documentation/dev-manual/debugging.rst +++ b/documentation/dev-manual/debugging.rst @@ -1235,7 +1235,7 @@ Here are some other tips that you might find useful: :yocto_bugs:`Bugzilla <>`. For information on how to submit a bug against the Yocto Project, see the Yocto Project Bugzilla :yocto_wiki:`wiki page ` - and the ":doc:`../contributor-guide/submit-defect`" section. + and the ":doc:`../contributor-guide/report-defect`" section. .. note:: diff --git a/documentation/ref-manual/resources.rst b/documentation/ref-manual/resources.rst index 324d1fad10..8c3726e83b 100644 --- a/documentation/ref-manual/resources.rst +++ b/documentation/ref-manual/resources.rst @@ -45,7 +45,7 @@ your expectations). For a general procedure and guidelines on how to use Bugzilla to submit a bug against the Yocto Project, see the following: -- The ":doc:`../contributor-guide/submit-defect`" +- The ":doc:`../contributor-guide/report-defect`" section in the Yocto Project and OpenEmbedded Contributor Guide. - The Yocto Project :yocto_wiki:`Bugzilla wiki page ` diff --git a/documentation/ref-manual/system-requirements.rst b/documentation/ref-manual/system-requirements.rst index 9ae7b4e63b..66ab65d2b7 100644 --- a/documentation/ref-manual/system-requirements.rst +++ b/documentation/ref-manual/system-requirements.rst @@ -134,7 +134,7 @@ tested by the &DISTRO; release ("&DISTRO_NAME;"), but no longer are: interested in hearing about your experience. For information on how to submit a bug, see the Yocto Project :yocto_wiki:`Bugzilla wiki page ` - and the ":doc:`../contributor-guide/submit-defect`" + and the ":doc:`../contributor-guide/report-defect`" section in the Yocto Project and OpenEmbedded Contributor Guide. Required Packages for the Build Host From patchwork Fri Aug 11 17:55:24 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Michael Opdenacker X-Patchwork-Id: 28708 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from aws-us-west-2-korg-lkml-1.web.codeaurora.org (localhost.localdomain [127.0.0.1]) by smtp.lore.kernel.org (Postfix) with ESMTP id 8E5ABC04A94 for ; Fri, 11 Aug 2023 17:55:44 +0000 (UTC) Received: from relay2-d.mail.gandi.net (relay2-d.mail.gandi.net [217.70.183.194]) by mx.groups.io with SMTP id smtpd.web11.49357.1691776539970405112 for ; Fri, 11 Aug 2023 10:55:40 -0700 Authentication-Results: mx.groups.io; dkim=pass header.i=@bootlin.com header.s=gm1 header.b=fgGMmdzn; spf=pass (domain: bootlin.com, ip: 217.70.183.194, mailfrom: michael.opdenacker@bootlin.com) Received: by mail.gandi.net (Postfix) with ESMTPSA id B24DA40002; Fri, 11 Aug 2023 17:55:37 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bootlin.com; s=gm1; t=1691776537; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=3MLYWkbSyrPRlxohwjdbgzyif2T+3sQ7p6wwZiFTUmU=; b=fgGMmdznR0aoKhdo/mfyoUy2oHJyvt3CqOHdY1JEpZKj01FJRxgatsfVXpYLRmzi730nej L9xt+8kI6f8vtET3rrdI6ajs8hooDYYM3FZGVq6ooKG13GetVbWD0kJ6bL+uQbGUrCwTqh p/WW3nZxW4IlIT505DJC1DPtq1+UEQHGu6hQUjBQr4bSxkPFWAEuGkqt0nLW/iWR0rbxz3 2Ltrfk8ACzG97mo8M5u3q6LE2mHPFeJ0MQmZVBsB4tSqPDx8eY3BsPNfFKYEQFkRc2KDvo fQcdMaSvEtCl4md3582uk0VetoJNcyQdYc366ZRY5/mpe0m6Om7GCaaYWSNL/g== From: michael.opdenacker@bootlin.com To: docs@lists.yoctoproject.org Cc: Michael Opdenacker Subject: [PATCH 2/5] contributor-guide: remove obsolete pkg-config guidelines Date: Fri, 11 Aug 2023 19:55:24 +0200 Message-Id: <20230811175527.1116864-3-michael.opdenacker@bootlin.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20230811175527.1116864-1-michael.opdenacker@bootlin.com> References: <20230811175527.1116864-1-michael.opdenacker@bootlin.com> MIME-Version: 1.0 X-GND-Sasl: michael.opdenacker@bootlin.com List-Id: X-Webhook-Received: from li982-79.members.linode.com [45.33.32.79] by aws-us-west-2-korg-lkml-1.web.codeaurora.org with HTTPS for ; Fri, 11 Aug 2023 17:55:44 -0000 X-Groupsio-URL: https://lists.yoctoproject.org/g/docs/message/4147 From: Michael Opdenacker They were coming from obsolete notes from the times when people directly created or modified .pc files from their recipes. Nobody should be doing that any more and keep this can be confusing. Signed-off-by: Michael Opdenacker --- documentation/contributor-guide/recipe-style-guide.rst | 5 ----- 1 file changed, 5 deletions(-) diff --git a/documentation/contributor-guide/recipe-style-guide.rst b/documentation/contributor-guide/recipe-style-guide.rst index 35ffbc61ef..a0d513e8e9 100644 --- a/documentation/contributor-guide/recipe-style-guide.rst +++ b/documentation/contributor-guide/recipe-style-guide.rst @@ -255,8 +255,3 @@ Tips and Guidelines for Writing Recipes - Use :term:`BBCLASSEXTEND` instead of creating separate recipes such as ``-native`` and ``-nativesdk`` ones, whenever possible. This avoids having to maintain multiple recipe files at the same time. - -- Avoid manually mangling ``pkg-config`` ``.pc`` files. - Recipes using ``pkg-config`` should use variables to ensure they are correctly - relocatable and not need manual path correction in the recipe. - From patchwork Fri Aug 11 17:55:25 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Michael Opdenacker X-Patchwork-Id: 28709 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from aws-us-west-2-korg-lkml-1.web.codeaurora.org (localhost.localdomain [127.0.0.1]) by smtp.lore.kernel.org (Postfix) with ESMTP id 85527EB64DD for ; Fri, 11 Aug 2023 17:55:44 +0000 (UTC) Received: from relay6-d.mail.gandi.net (relay6-d.mail.gandi.net [217.70.183.198]) by mx.groups.io with SMTP id smtpd.web11.49358.1691776540916388957 for ; Fri, 11 Aug 2023 10:55:41 -0700 Authentication-Results: mx.groups.io; dkim=pass header.i=@bootlin.com header.s=gm1 header.b=X0k/8zDe; spf=pass (domain: bootlin.com, ip: 217.70.183.198, mailfrom: michael.opdenacker@bootlin.com) Received: by mail.gandi.net (Postfix) with ESMTPSA id DDA04C0003; Fri, 11 Aug 2023 17:55:38 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bootlin.com; s=gm1; t=1691776539; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=CSyK8BZJUG1g24H28CiNTDpgAZfD/fIowBfBDprj4KU=; b=X0k/8zDeoxzOYIXhlM7gPp5FlKYGwJ5bpX48ZClF/FhfHtXP0W1yHtDLlrRCONvppmQ8Op wmNUC/vHUICiH5P+MK2UfyV7pWrXQcEPSwknWrjL1AelbglbpDkOQmshFKq+ZA6E7pndyD Tgf4EqYmkqCIVcoFZmradHLZsKnizLcmMYdMI/5xfpqS0nEo8h59Bbj0wEhkNmLC34FHrs GprsY4PepLrewBO0HDRnckjJQWsRoZueNVoGToVYuOLGlkk7iN29qfI/KGex84DG+/NtiK upJCdYX0JWXzD2OxZxkVXb9Jz9/ALWQu/Wcun0c+dCtQAYEcOWt8pxoyRHkn0w== From: michael.opdenacker@bootlin.com To: docs@lists.yoctoproject.org Cc: Michael Opdenacker Subject: [PATCH 3/5] contributor guide: remove unnecessary information about mailing lists Date: Fri, 11 Aug 2023 19:55:25 +0200 Message-Id: <20230811175527.1116864-4-michael.opdenacker@bootlin.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20230811175527.1116864-1-michael.opdenacker@bootlin.com> References: <20230811175527.1116864-1-michael.opdenacker@bootlin.com> MIME-Version: 1.0 X-GND-Sasl: michael.opdenacker@bootlin.com List-Id: X-Webhook-Received: from li982-79.members.linode.com [45.33.32.79] by aws-us-west-2-korg-lkml-1.web.codeaurora.org with HTTPS for ; Fri, 11 Aug 2023 17:55:44 -0000 X-Groupsio-URL: https://lists.yoctoproject.org/g/docs/message/4148 From: Michael Opdenacker The mailing lists for sending code are sufficient! Signed-off-by: Michael Opdenacker --- documentation/contributor-guide/submit-change.rst | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/documentation/contributor-guide/submit-change.rst b/documentation/contributor-guide/submit-change.rst index 1327b2854c..3fd2b049cf 100644 --- a/documentation/contributor-guide/submit-change.rst +++ b/documentation/contributor-guide/submit-change.rst @@ -226,9 +226,7 @@ Using Email to Submit a Patch Depending on the components changed, you need to submit the email to a specific mailing list. For some guidance on which mailing list to use, see the ":ref:`contributor-guide/submit-change:finding a suitable mailing list`" -section above. For a description of all the available -mailing lists, see the ":ref:`Mailing Lists `" section in the -Yocto Project Reference Manual. +section above. Here is the general procedure on how to submit a patch through email without using the scripts once the steps in @@ -369,10 +367,9 @@ have been followed: you can see who is responsible for the bulk of the changes against the file. - - *Examine the List of Mailing Lists:* For a list of the Yocto - Project and related mailing lists, see the ":ref:`Mailing - lists `" section in - the Yocto Project Reference Manual. + - *Find the Mailing List to Use:* See the + ":ref:`contributor-guide/submit-change:finding a suitable mailing list`" + section above. #. *Make a Pull Request:* Notify the maintainer or the mailing list that you have pushed a change by making a pull request. From patchwork Fri Aug 11 17:55:26 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Michael Opdenacker X-Patchwork-Id: 28707 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from aws-us-west-2-korg-lkml-1.web.codeaurora.org (localhost.localdomain [127.0.0.1]) by smtp.lore.kernel.org (Postfix) with ESMTP id 8162BC41513 for ; Fri, 11 Aug 2023 17:55:44 +0000 (UTC) Received: from relay8-d.mail.gandi.net (relay8-d.mail.gandi.net [217.70.183.201]) by mx.groups.io with SMTP id smtpd.web11.49359.1691776541516767717 for ; Fri, 11 Aug 2023 10:55:41 -0700 Authentication-Results: mx.groups.io; dkim=pass header.i=@bootlin.com header.s=gm1 header.b=aXA0gBUL; spf=pass (domain: bootlin.com, ip: 217.70.183.201, mailfrom: michael.opdenacker@bootlin.com) Received: by mail.gandi.net (Postfix) with ESMTPSA id 0D55A1BF205; Fri, 11 Aug 2023 17:55:39 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bootlin.com; s=gm1; t=1691776540; 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=9nlwFh0IohGBDksZdgoKGw2jYvr93J5osBATbKAo5ig=; b=aXA0gBUL79MkYUGBsnj2f8nCygKH1bFczn7wNNfaRtXN+VNsnrkEnK3Ga5MO/+5dby0Xij BSIj73Lgm2Ya9eDqgcRPSKfHPNCCHTUzO/k/Kb5eBPRB7ZzT/Y2xB9vwqLvFOE/IxAJoP+ kOLG2zBH0dpTFQVfiA3GZOtNLuh/OnJO9Gh9l8Xnh1Ya3NH6M4jLa9iowI4S3Qu0nUPgWW Oj8BYw8ETcZ9zOt2/DbRfO5XYs32Gx0k9o9AwOBzTipMzEY7t3YnTAGP7yNFpfCA2Euvdk WynefJGyhxwIUEmoz+qMvvycUh2phkAvzKxVS7arKP6SnGAkDscBzw7l44Rf5Q== From: michael.opdenacker@bootlin.com To: docs@lists.yoctoproject.org Cc: Michael Opdenacker Subject: [PATCH 4/5] contributor-guide: clarification about patchtest Date: Fri, 11 Aug 2023 19:55:26 +0200 Message-Id: <20230811175527.1116864-5-michael.opdenacker@bootlin.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20230811175527.1116864-1-michael.opdenacker@bootlin.com> References: <20230811175527.1116864-1-michael.opdenacker@bootlin.com> MIME-Version: 1.0 X-GND-Sasl: michael.opdenacker@bootlin.com List-Id: X-Webhook-Received: from li982-79.members.linode.com [45.33.32.79] by aws-us-west-2-korg-lkml-1.web.codeaurora.org with HTTPS for ; Fri, 11 Aug 2023 17:55:44 -0000 X-Groupsio-URL: https://lists.yoctoproject.org/g/docs/message/4149 From: Michael Opdenacker - Highlight that patchtest still needs improving - Fix reference to this tool Signed-off-by: Michael Opdenacker --- documentation/contributor-guide/submit-change.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/documentation/contributor-guide/submit-change.rst b/documentation/contributor-guide/submit-change.rst index 3fd2b049cf..6bee423bfb 100644 --- a/documentation/contributor-guide/submit-change.rst +++ b/documentation/contributor-guide/submit-change.rst @@ -43,7 +43,7 @@ mailing list approach off-putting and would prefer a web-based GUI. Since we don’t believe that can work for us, the project is aiming to ensure `patchwork `__ is available to help track patch status and also looking at how tooling can provide more feedback to users -about patch status. We are looking at tools such as ``patchtest`` to +about patch status. We are looking at improving tools such as ``patchtest`` to test user contributions before they hit the mailing lists and also at better documenting how to use such workflows since we recognise that whilst this was common knowledge a decade ago, it might not be as familiar now. @@ -299,7 +299,7 @@ The Yocto Project uses a `Patchwork instance X-Patchwork-Id: 28710 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from aws-us-west-2-korg-lkml-1.web.codeaurora.org (localhost.localdomain [127.0.0.1]) by smtp.lore.kernel.org (Postfix) with ESMTP id 8A083EB64DD for ; Fri, 11 Aug 2023 17:55:54 +0000 (UTC) Received: from relay8-d.mail.gandi.net (relay8-d.mail.gandi.net [217.70.183.201]) by mx.groups.io with SMTP id smtpd.web10.49493.1691776547524667420 for ; Fri, 11 Aug 2023 10:55:47 -0700 Authentication-Results: mx.groups.io; dkim=pass header.i=@bootlin.com header.s=gm1 header.b=WVqijEoV; spf=pass (domain: bootlin.com, ip: 217.70.183.201, mailfrom: michael.opdenacker@bootlin.com) Received: by mail.gandi.net (Postfix) with ESMTPSA id DE7F81BF206; Fri, 11 Aug 2023 17:55:45 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bootlin.com; s=gm1; t=1691776546; 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=/LjNA9bUqSQPc78Wz4bvXcifvRRrrBD9WlGamVSupCM=; b=WVqijEoV3k16AE3440lzsFlmJIh1hSxMFRubs2ehSmpXKIiHDBwp+AgGHZUsS2E4GOs1Na BK8CFy9ecqXq5ZxLMbs2U7+KrJPbr8zIcdpFxFiVOCqSsQA9XFL9oAkpzwst5B3w4Cc13w UXrOcmWP0KCx4TsdJOCkeG5Z5X04JXsCbb7vZqCMjJjyhI8znfyeivE8/9wr41HE6/hHai QyZMjx6ApfJdMrdHDKQ6ZYsqQmlekUAVJhIoIqSzC+h1Pmf3TUQDvNpQlrkWfl7MKJpMCT 9ewigY/TJf96Lk+qEo/oXe38WTXQpiKjCbaoLwWZgitIN+Q/Mk6jLyV0k8C/8w== From: michael.opdenacker@bootlin.com To: docs@lists.yoctoproject.org Cc: Michael Opdenacker Subject: [PATCH 5/5] contributor guide: update instructions for making and sharing changes Date: Fri, 11 Aug 2023 19:55:27 +0200 Message-Id: <20230811175527.1116864-6-michael.opdenacker@bootlin.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20230811175527.1116864-1-michael.opdenacker@bootlin.com> References: <20230811175527.1116864-1-michael.opdenacker@bootlin.com> MIME-Version: 1.0 X-GND-Sasl: michael.opdenacker@bootlin.com List-Id: X-Webhook-Received: from li982-79.members.linode.com [45.33.32.79] by aws-us-west-2-korg-lkml-1.web.codeaurora.org with HTTPS for ; Fri, 11 Aug 2023 17:55:54 -0000 X-Groupsio-URL: https://lists.yoctoproject.org/g/docs/message/4150 From: Michael Opdenacker - Shifting the focus to multiple changes instead of just one - Advising to create a branch for changes - Removing unnecessary or too verbose explanations - Adding useful resources and examples Signed-off-by: Michael Opdenacker --- documentation/bsp-guide/bsp.rst | 2 +- documentation/contributor-guide/index.rst | 2 +- .../{submit-change.rst => submit-changes.rst} | 132 +++++++++--------- documentation/dev-manual/debugging.rst | 2 +- documentation/dev-manual/start.rst | 4 +- documentation/dev-manual/vulnerabilities.rst | 2 +- .../development-environment.rst | 6 +- 7 files changed, 77 insertions(+), 73 deletions(-) rename documentation/contributor-guide/{submit-change.rst => submit-changes.rst} (85%) diff --git a/documentation/bsp-guide/bsp.rst b/documentation/bsp-guide/bsp.rst index 52a07cfcb0..3be314bcf6 100644 --- a/documentation/bsp-guide/bsp.rst +++ b/documentation/bsp-guide/bsp.rst @@ -927,7 +927,7 @@ Yocto Project: - The name and contact information for the BSP layer maintainer. This is the person to whom patches and questions should be sent. For information on how to find the right person, see the - :doc:`../contributor-guide/submit-change` section in the Yocto Project and + :doc:`../contributor-guide/submit-changes` section in the Yocto Project and OpenEmbedded Contributor Guide. - Instructions on how to build the BSP using the BSP layer. diff --git a/documentation/contributor-guide/index.rst b/documentation/contributor-guide/index.rst index 8fa65045a3..a832169455 100644 --- a/documentation/contributor-guide/index.rst +++ b/documentation/contributor-guide/index.rst @@ -21,6 +21,6 @@ this. identify-component report-defect recipe-style-guide - submit-change + submit-changes .. include:: /boilerplate.rst diff --git a/documentation/contributor-guide/submit-change.rst b/documentation/contributor-guide/submit-changes.rst similarity index 85% rename from documentation/contributor-guide/submit-change.rst rename to documentation/contributor-guide/submit-changes.rst index 6bee423bfb..3f6d2db96c 100644 --- a/documentation/contributor-guide/submit-change.rst +++ b/documentation/contributor-guide/submit-changes.rst @@ -1,6 +1,6 @@ .. SPDX-License-Identifier: CC-BY-SA-2.0-UK -Contributing a Change to a Component +Contributing Changes to a Component ************************************ Contributions to the Yocto Project and OpenEmbedded are very welcome. @@ -60,13 +60,13 @@ list you need to use depends on the location of the code you are changing. Each component (e.g. layer) should have a ``README`` file that indicates where to send the changes and which process to follow. -You can send the patch to the mailing list using whichever approach you -feel comfortable with to generate the patch. Once sent, the patch is +You can send the patches to the mailing list using whichever approach you +feel comfortable with to generate the patches. Once sent, the patches are usually reviewed by the community at large. If somebody has concerns -with the patch, they will usually voice their concern over the mailing -list. If a patch does not receive any negative reviews, the maintainer -of the affected layer typically takes the patch, tests it, and then -based on successful testing, merges the patch. +any of the the patches, they will usually voice their concern over the mailing +list. If patches do not receive any negative reviews, the maintainer +of the affected layer typically takes them, tests them, and then +based on successful testing, merges them. The "poky" repository, which is the Yocto Project's reference build environment, is a hybrid repository that contains several individual @@ -74,13 +74,13 @@ pieces (e.g. BitBake, Metadata, documentation, and so forth) built using the combo-layer tool. The upstream location used for submitting changes varies by component: -- *Core Metadata:* Send your patch to the +- *Core Metadata:* Send your patches to the :oe_lists:`openembedded-core ` mailing list. For example, a change to anything under the ``meta`` or ``scripts`` directories should be sent to this mailing list. - *BitBake:* For changes to BitBake (i.e. anything under the - ``bitbake`` directory), send your patch to the + ``bitbake`` directory), send your patches to the :oe_lists:`bitbake-devel ` mailing list. @@ -101,13 +101,13 @@ repositories (i.e. ``yoctoproject.org``) and tools use the For additional recipes that do not fit into the core Metadata, you should determine which layer the recipe should go into and submit the -change in the manner recommended by the documentation (e.g. the +changes in the manner recommended by the documentation (e.g. the ``README`` file) supplied with the layer. If in doubt, please ask on the :yocto_lists:`yocto ` general mailing list or on the :oe_lists:`openembedded-devel ` mailing list. -You can also push a change upstream and request a maintainer to pull the -change into the component's upstream repository. You do this by pushing +You can also push changes upstream and request a maintainer to pull the +changes into the component's upstream repository. You do this by pushing to a contribution repository that is upstream. See the ":ref:`overview-manual/development-environment:git workflows and the yocto project`" section in the Yocto Project Overview and Concepts Manual for additional @@ -135,29 +135,43 @@ Other layers may have similar testing branches but there is no formal requirement or standard for these so please check the documentation for the layers you are contributing to. -The following sections provide procedures for submitting a change. +The following sections provide procedures for submitting changes. Preparing Changes for Submission ================================ -#. *Make Your Changes Locally:* Make your changes in your local Git - repository. You should make small, controlled, isolated changes. - Keeping changes small and isolated aids review, makes - merging/rebasing easier and keeps the change history clean should - anyone need to refer to it in future. +The first thing to do is to create a new branch in your local Git repository +for your changes, starting from the reference branch in the upstream +repository (often called ``master``):: -#. *Stage Your Changes:* Stage your changes by using the ``git add`` - command on each file you changed. + $ git checkout + $ git checkout -b my-changes -#. *Commit Your Changes:* Commit the change by using the ``git commit`` +If you have completely unrelated sets of changes to submit, you should even +create one branch for each set. + +Then, in each branch, you should group your changes into small, controlled and +isolated ones. Keeping changes small and isolated aids review, makes +merging/rebasing easier and keeps the change history clean should anyone need +to refer to it in future. + +To this purpose, you should create *one Git commit per change*, +corresponding to each of the patches you will eventually submit. +So, for each identified change: + +#. *Stage Your Change:* Stage your change by using the ``git add`` + command on each file you modified. + +#. *Commit Your Change:* Commit the change by using the ``git commit`` command. Make sure your commit information follows standards by following these accepted conventions: - Be sure to include a "Signed-off-by:" line in the same style as required by the Linux kernel. This can be done by using the ``git commit -s`` command. Adding this line signifies that you, - the submitter, have agreed to the Developer's Certificate of - Origin 1.1 as follows: + the submitter, have agreed to the `Developer's Certificate of Origin 1.1 + `__ + as follows: .. code-block:: none @@ -196,6 +210,14 @@ Preparing Changes for Submission with the recipe name (if changing a recipe), or else with the short form path to the file being changed. + .. note:: + + To find a suitable prefix for the commit summary, a good idea + is to look for prefixes used in previous commits touching the + same files or directories:: + + git log --oneline + - For the body of the commit message, provide detailed information that describes what you changed, why you made the change, and the approach you used. It might also be helpful if you mention how you @@ -220,50 +242,30 @@ Preparing Changes for Submission detailed description of change -Using Email to Submit a Patch +Using Email to Submit Patches ============================= Depending on the components changed, you need to submit the email to a specific mailing list. For some guidance on which mailing list to use, -see the ":ref:`contributor-guide/submit-change:finding a suitable mailing list`" +see the ":ref:`contributor-guide/submit-changes:finding a suitable mailing list`" section above. -Here is the general procedure on how to submit a patch through email -without using the scripts once the steps in -":ref:`contributor-guide/submit-change:preparing changes for submission`" -have been followed: - -#. *Format the Commit:* Format the commit into an email message. To - format commits, use the ``git format-patch`` command. When you - provide the command, you must include a revision list or a number of - patches as part of the command. For example, either of these two - commands takes your most recent single commit and formats it as an - email message in the current directory:: - - $ git format-patch -1 - - or :: +Here is the general procedure on how to create and submit patches through email: - $ git format-patch HEAD~ +#. *Generate Patches for your Branch:* The ``git format-patch`` command for + generate patch files for each of the commits in your branch. You need + to pass the reference branch your branch starts from:: - After the command is run, the current directory contains a numbered - ``.patch`` file for the commit. + $ git format-patch - If you provide several commits as part of the command, the - ``git format-patch`` command produces a series of numbered files in - the current directory – one for each commit. If you have more than - one patch, you should also use the ``--cover`` option with the - command, which generates a cover letter as the first "patch" in the - series. You can then edit the cover letter to provide a description - for the series of patches. For information on the - ``git format-patch`` command, see ``GIT_FORMAT_PATCH(1)`` displayed - using the ``man git-format-patch`` command. + After the command is run, the current directory contains numbered + ``.patch`` files for the commits in your branch. - .. note:: - - If you are or will be a frequent contributor to the Yocto Project - or to OpenEmbedded, you might consider requesting a contrib area - and the necessary associated rights. + If you have more than one patch, you should also use the ``--cover`` + option with the command, which generates a cover letter as the first + "patch" in the series. You can then edit the cover letter to provide + a description for the series of patches. Run ``man git-format-patch`` + for details about this command. #. *Send the patches via email:* Send the patches to the recipients and relevant mailing lists by using the ``git send-email`` command. @@ -291,9 +293,11 @@ have been followed: whitespace in the body of the message, which can occur when you use your own mail client. The command also has several options that let you specify recipients and perform further editing of the email - message. For information on how to use the ``git send-email`` - command, see ``GIT-SEND-EMAIL(1)`` displayed using the - ``man git-send-email`` command. + message. Here's a typical usage of this command:: + + git send-email --to *.patch + + Run ``man git-send-email`` for more details about this command. The Yocto Project uses a `Patchwork instance `__ to track the status of patches submitted to the various mailing lists and to @@ -320,7 +324,7 @@ patch series with a link to the branch for review. Follow this procedure to push a change to an upstream "contrib" Git repository once the steps in -":ref:`contributor-guide/submit-change:preparing changes for submission`" +":ref:`contributor-guide/submit-changes:preparing changes for submission`" have been followed: .. note:: @@ -368,7 +372,7 @@ have been followed: the file. - *Find the Mailing List to Use:* See the - ":ref:`contributor-guide/submit-change:finding a suitable mailing list`" + ":ref:`contributor-guide/submit-changes:finding a suitable mailing list`" section above. #. *Make a Pull Request:* Notify the maintainer or the mailing list that @@ -491,8 +495,8 @@ follows: a newer version of the software which includes an upstream fix for the issue or when the issue has been fixed on the master branch in a way that introduces backwards incompatible changes. In this case follow the - steps in ":ref:`contributor-guide/submit-change:preparing changes for submission`" and - ":ref:`contributor-guide/submit-change:using email to submit a patch`" + steps in ":ref:`contributor-guide/submit-changes:preparing changes for submission`" and + ":ref:`contributor-guide/submit-changes:using email to submit patches`" but modify the subject header of your patch email to include the name of the stable branch which you are targetting. This can be done using the ``--subject-prefix`` argument to diff --git a/documentation/dev-manual/debugging.rst b/documentation/dev-manual/debugging.rst index 890578cc05..fea2cb30a1 100644 --- a/documentation/dev-manual/debugging.rst +++ b/documentation/dev-manual/debugging.rst @@ -879,7 +879,7 @@ The build should work without issue. As with all solved problems, if they originated upstream, you need to submit the fix for the recipe in OE-Core and upstream so that the problem is taken care of at its source. See the -":doc:`../contributor-guide/submit-change`" section for more information. +":doc:`../contributor-guide/submit-changes`" section for more information. Debugging With the GNU Project Debugger (GDB) Remotely ====================================================== diff --git a/documentation/dev-manual/start.rst b/documentation/dev-manual/start.rst index 372959d9ed..88afa27ad5 100644 --- a/documentation/dev-manual/start.rst +++ b/documentation/dev-manual/start.rst @@ -246,13 +246,13 @@ particular working environment and set of practices. - The Yocto Project community encourages you to send patches to the project to fix bugs or add features. If you do submit patches, follow the project commit guidelines for writing good commit - messages. See the ":doc:`../contributor-guide/submit-change`" + messages. See the ":doc:`../contributor-guide/submit-changes`" section in the Yocto Project and OpenEmbedded Contributor Guide. - Send changes to the core sooner than later as others are likely to run into the same issues. For some guidance on mailing lists to use, see the lists in the - ":ref:`contributor-guide/submit-change:finding a suitable mailing list`" + ":ref:`contributor-guide/submit-changes:finding a suitable mailing list`" section. For a description of the available mailing lists, see the ":ref:`resources-mailinglist`" section in the Yocto Project Reference Manual. diff --git a/documentation/dev-manual/vulnerabilities.rst b/documentation/dev-manual/vulnerabilities.rst index 297789dae6..71111bb3e2 100644 --- a/documentation/dev-manual/vulnerabilities.rst +++ b/documentation/dev-manual/vulnerabilities.rst @@ -22,7 +22,7 @@ issues may be impacting Poky and OE-Core. It is up to the maintainers, users, contributors and anyone interested in the issues to investigate and possibly fix them by updating software components to newer versions or by applying patches to address them. It is recommended to work with Poky and OE-Core upstream maintainers and submit -patches to fix them, see ":doc:`../contributor-guide/submit-change`" for details. +patches to fix them, see ":doc:`../contributor-guide/submit-changes`" for details. Vulnerability check at build time ================================= diff --git a/documentation/overview-manual/development-environment.rst b/documentation/overview-manual/development-environment.rst index 55f34c18da..262d5cb203 100644 --- a/documentation/overview-manual/development-environment.rst +++ b/documentation/overview-manual/development-environment.rst @@ -264,7 +264,7 @@ push them into the "contrib" area and subsequently request that the maintainer include them into an upstream branch. This process is called "submitting a patch" or "submitting a change." For information on submitting patches and changes, see the -":doc:`../contributor-guide/submit-change`" section in the Yocto Project +":doc:`../contributor-guide/submit-changes`" section in the Yocto Project and OpenEmbedded Contributor Guide. In summary, there is a single point of entry for changes into the @@ -330,7 +330,7 @@ Book `__. release to facilitate this workflow. You can find these scripts in the ``scripts`` folder of the :term:`Source Directory`. For information on how to use these scripts, see the - ":ref:`contributor-guide/submit-change:using scripts to push a change upstream and request a pull`" + ":ref:`contributor-guide/submit-changes:using scripts to push a change upstream and request a pull`" section in the Yocto Project and OpenEmbedded Contributor Guide. - *Patch Workflow:* This workflow allows you to notify the maintainer @@ -339,7 +339,7 @@ Book `__. this type of change, you format the patch and then send the email using the Git commands ``git format-patch`` and ``git send-email``. For information on how to use these scripts, see the - ":doc:`../contributor-guide/submit-change`" section in the Yocto Project + ":doc:`../contributor-guide/submit-changes`" section in the Yocto Project and OpenEmbedded Contributor Guide. Git