From patchwork Thu Oct 5 20:04:45 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Michael Opdenacker X-Patchwork-Id: 31736 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 47979E9273E for ; Thu, 5 Oct 2023 20:05:03 +0000 (UTC) Received: from relay5-d.mail.gandi.net (relay5-d.mail.gandi.net [217.70.183.197]) by mx.groups.io with SMTP id smtpd.web11.25996.1696536302180628518 for ; Thu, 05 Oct 2023 13:05:02 -0700 Authentication-Results: mx.groups.io; dkim=pass header.i=@bootlin.com header.s=gm1 header.b=LlzCk4/2; spf=pass (domain: bootlin.com, ip: 217.70.183.197, mailfrom: michael.opdenacker@bootlin.com) Received: by mail.gandi.net (Postfix) with ESMTPSA id 978E61C0006; Thu, 5 Oct 2023 20:05:00 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bootlin.com; s=gm1; t=1696536300; 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; bh=oJqlVD2xctWRWK/WOPTZVNcLW8APwlw2NfNewjNPswU=; b=LlzCk4/2ZqQrudkXvir645Yc/MhrnHNhayNPJIna79qQYFtqb9v3Pfa57gwGb/iJsP9Miy mf2110Fq5Aft/p+Si49dzr1/31g7PhalXpRQ9htYUw9617iuBfDi/CR7DQNZsqwoloZMgh pcoIirrbbwjjn7t3PhUdA3Bg1hjBBrsEo4F+CuRZoMK9u2oKh//j2WBfCMawaR0xceueH/ orcn70oy3tYUZ1FcXEp63rifu/0aY4CQOYMaBx61RdidTozYsX2pb6yR1h5D5WdfpEB9Qp hBBeUgKiYDennj6ha3INoLlCNv2QVm9h4L4GHnYFHEGM9c4syMtYrIxr8Gb6Tg== From: michael.opdenacker@bootlin.com To: docs@lists.yoctoproject.org Cc: Michael Opdenacker , Richard Purdie Subject: [mickledore][PATCH 1/9] contributor-guide/style-guide: Refer to recipes, not packages Date: Thu, 5 Oct 2023 22:04:45 +0200 Message-Id: <20231005200453.2873299-1-michael.opdenacker@bootlin.com> X-Mailer: git-send-email 2.34.1 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 ; Thu, 05 Oct 2023 20:05:03 -0000 X-Groupsio-URL: https://lists.yoctoproject.org/g/docs/message/4319 From: Michael Opdenacker From: Richard Purdie Whilst often referred to as packages by people we should use the more accurate term in documentation, 'recipe' instead of 'packages'. Signed-off-by: Richard Purdie Reviewed-by: Michael Opdenacker --- .../contributor-guide/recipe-style-guide.rst | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/documentation/contributor-guide/recipe-style-guide.rst b/documentation/contributor-guide/recipe-style-guide.rst index 99105179a6..1a1c1c6ee2 100644 --- a/documentation/contributor-guide/recipe-style-guide.rst +++ b/documentation/contributor-guide/recipe-style-guide.rst @@ -7,17 +7,18 @@ Recipe Naming Conventions ========================= In general, most recipes should follow the naming convention -``recipes-category/package/packagename_version.bb``. Recipes for related -projects may share the same package directory. ``packagename``, ``category``, -and ``package`` may contain hyphens, but hyphens are not allowed in ``version``. +``recipes-category/recipename/recipename_version.bb``. Recipes for related +projects may share the same recipe directory. ``recipename`` and ``category`` +may contain hyphens, but hyphens are not allowed in ``version``. If the recipe is tracking a Git revision that does not correspond to a released -version of the software, ``version`` may be ``git`` (e.g. ``packagename_git.bb``) +version of the software, ``version`` may be ``git`` (e.g. ``recipename_git.bb``) +and the recipe would set :term:`PV`. Version Policy ============== -Our versions follow the form ``:-`` +Our versions follow the form ``:-`` or in BitBake variable terms ${:term:`PE`}:${:term:`PV`}-${:term:`PR`}. We generally follow the `Debian `__ version policy which defines these terms. @@ -26,7 +27,7 @@ In most cases the version :term:`PV` will be set automatically from the recipe file name. It is recommended to use released versions of software as these are revisions that upstream are expecting people to use. -Package versions should always compare and sort correctly so that upgrades work +Recipe versions should always compare and sort correctly so that upgrades work as expected. With conventional versions such as ``1.4`` upgrading ``to 1.5`` this happens naturally, but some versions don't sort. For example, ``1.5 Release Candidate 2`` could be written as ``1.5rc2`` but this sorts after @@ -62,7 +63,7 @@ Version Number Changes The :term:`PR` variable is used to indicate different revisions of a recipe that reference the same upstream source version. It can be used to force a -new version of a package to be installed onto a device from a package feed. +new version of a recipe to be installed onto a device from a package feed. These once had to be set manually but in most cases these can now be set and incremented automatically by a PR Server connected with a package feed. From patchwork Thu Oct 5 20:04:46 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Michael Opdenacker X-Patchwork-Id: 31738 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 4C4BFE9370C for ; Thu, 5 Oct 2023 20:05:13 +0000 (UTC) Received: from relay9-d.mail.gandi.net (relay9-d.mail.gandi.net [217.70.183.199]) by mx.groups.io with SMTP id smtpd.web11.25998.1696536303046754628 for ; Thu, 05 Oct 2023 13:05:03 -0700 Authentication-Results: mx.groups.io; dkim=pass header.i=@bootlin.com header.s=gm1 header.b=PtJhW82n; spf=pass (domain: bootlin.com, ip: 217.70.183.199, mailfrom: michael.opdenacker@bootlin.com) Received: by mail.gandi.net (Postfix) with ESMTPSA id 3D8FBFF809; Thu, 5 Oct 2023 20:05:01 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bootlin.com; s=gm1; t=1696536301; 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=fF1gg/GHRmXQh0W4kMMQtQO9oaY5mGZRPenMq3z1vVo=; b=PtJhW82ndxfPjYqUlqWyXIbcJ6IXHD+9PsUO7cc8prhsT6MZD3eyBkbWVuc9YNAR2nWccA Go8faT4Ai/nDV/4GmTOnbkPbiRzu2w1QcgfJhRHkC+Dq1OaYOlHY/k9a2rmLNOCnC1jVZB +Q+r9GCgoeMUgauL2MwgTsYJ+F2ZcCD1gKa4RpXUU0G7uuZ+95FzltJ8LGpuaGoLWIL44U 2TvRYqhHxXuiOy0gHZ1bQmV1jqXvBwWXwv4fkq9Gvsocr/FSZxbekE2T7MqjRM6F+3x7x3 clteWViXYamLVKcJncKSd+GGNm/94PjM+U2QiRjDUPSkCM/iqaMXgsnibcp/Bw== From: michael.opdenacker@bootlin.com To: docs@lists.yoctoproject.org Cc: Michael Opdenacker , Richard Purdie , Yoann Congal Subject: [mickledore][PATCH 2/9] contributor-guide/style-guide: Add a note about task idempotence Date: Thu, 5 Oct 2023 22:04:46 +0200 Message-Id: <20231005200453.2873299-2-michael.opdenacker@bootlin.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20231005200453.2873299-1-michael.opdenacker@bootlin.com> References: <20231005200453.2873299-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 ; Thu, 05 Oct 2023 20:05:13 -0000 X-Groupsio-URL: https://lists.yoctoproject.org/g/docs/message/4320 From: Michael Opdenacker From: Richard Purdie Signed-off-by: Richard Purdie CC: Yoann Congal --- Changes in V2: - Use a bulleted list to clarify the order of steps (Suggested by Yoann Congal) - Recall that we are talking about idempotence in tasks. Useful for people overlooking the previous paragraph. --- .../contributor-guide/recipe-style-guide.rst | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/documentation/contributor-guide/recipe-style-guide.rst b/documentation/contributor-guide/recipe-style-guide.rst index 1a1c1c6ee2..b63172bd77 100644 --- a/documentation/contributor-guide/recipe-style-guide.rst +++ b/documentation/contributor-guide/recipe-style-guide.rst @@ -257,6 +257,20 @@ Tips and Guidelines for Writing Recipes and ``-nativesdk`` ones, whenever possible. This avoids having to maintain multiple recipe files at the same time. +- Recipes should have tasks which are idempotent, i.e. that executing a given task + multiple times shouldn't change the end result. The build environment is built upon + this assumption and breaking it can cause obscure build failures. + +- For idempotence when modifying files in tasks, it is usually best to: + + - copy a file ``X`` to ``X.orig`` (only if it doesn't exist already) + - then, copy ``X.orig`` back to ``X``, + - and, finally, modify ``X``. + + This ensures if rerun the task always has the same end result and the + original file can be preserved to reuse. It also guards against an + interrupted build corrupting the file. + Patch Upstream Status ===================== From patchwork Thu Oct 5 20:04:47 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Michael Opdenacker X-Patchwork-Id: 31741 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 49C83E9273F for ; Thu, 5 Oct 2023 20:05:13 +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.web10.25924.1696536303606778538 for ; Thu, 05 Oct 2023 13:05:03 -0700 Authentication-Results: mx.groups.io; dkim=pass header.i=@bootlin.com header.s=gm1 header.b=dDfAYmqo; spf=pass (domain: bootlin.com, ip: 217.70.183.194, mailfrom: michael.opdenacker@bootlin.com) Received: by mail.gandi.net (Postfix) with ESMTPSA id 193BF40005; Thu, 5 Oct 2023 20:05:01 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bootlin.com; s=gm1; t=1696536302; 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=hFudwXRfCDVigOTqDUtCWzeMuOcRKpZ101qzVgPq/98=; b=dDfAYmqoROBlevoxvdM2IkI6k4VBkC6C4XaaZYC8u8h93dTSGlGsfVlj1irC+cLN9/DgjN caqeIh6Ezo8yInyLjEOoI7rB0ubZdGMNQzdXqalHP3qvFQm9L4kCAjh/WDBMepIlVf+4N2 1nKZVOxdx9Uvo60yT/Zu17SOwwiNfA7IXfLxjH2OlSuXhh9n2fTVbzBRHBM8BTjvQg+DRQ g/U54/ddCbhurKxVSjt8R5POkNLapGjy11BH3Clcqi2Z3evHNo9HI6Dh0BO1aL7gRap9hQ JAUDzTZ/ak69xXoTUtqwCgwrYGVkw/JkOblTzX/3hh/nfiZLzBs2v5PtV+Bqtg== From: michael.opdenacker@bootlin.com To: docs@lists.yoctoproject.org Cc: Michael Opdenacker Subject: [mickledore][PATCH 3/9] bsp-guide: bsp.rst: replace reference to wiki Date: Thu, 5 Oct 2023 22:04:47 +0200 Message-Id: <20231005200453.2873299-3-michael.opdenacker@bootlin.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20231005200453.2873299-1-michael.opdenacker@bootlin.com> References: <20231005200453.2873299-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 ; Thu, 05 Oct 2023 20:05:13 -0000 X-Groupsio-URL: https://lists.yoctoproject.org/g/docs/message/4321 From: Michael Opdenacker Signed-off-by: Michael Opdenacker --- documentation/bsp-guide/bsp.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/documentation/bsp-guide/bsp.rst b/documentation/bsp-guide/bsp.rst index 3be314bcf6..c78fbeb68f 100644 --- a/documentation/bsp-guide/bsp.rst +++ b/documentation/bsp-guide/bsp.rst @@ -893,8 +893,8 @@ Yocto Project: ``recipes-*`` subdirectories specific to the recipe's function, or within a subdirectory containing a set of closely-related recipes. The recipes themselves should follow the general guidelines for - recipes used in the Yocto Project found in the ":oe_wiki:`OpenEmbedded - Style Guide `". + recipes found in the ":doc:`../contributor-guide/recipe-style-guide`" + in the Yocto Project and OpenEmbedded Contributor Guide. - *License File:* You must include a license file in the ``meta-bsp_root_name`` directory. This license covers the BSP From patchwork Thu Oct 5 20:04:48 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Michael Opdenacker X-Patchwork-Id: 31737 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 5C73EE93712 for ; Thu, 5 Oct 2023 20:05:13 +0000 (UTC) Received: from relay1-d.mail.gandi.net (relay1-d.mail.gandi.net [217.70.183.193]) by mx.groups.io with SMTP id smtpd.web10.25925.1696536304608016480 for ; Thu, 05 Oct 2023 13:05:04 -0700 Authentication-Results: mx.groups.io; dkim=pass header.i=@bootlin.com header.s=gm1 header.b=StYu8cZy; spf=pass (domain: bootlin.com, ip: 217.70.183.193, mailfrom: michael.opdenacker@bootlin.com) Received: by mail.gandi.net (Postfix) with ESMTPSA id A0621240004; Thu, 5 Oct 2023 20:05:02 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bootlin.com; s=gm1; t=1696536302; 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=JwnLQXy4n6leHDqLTxYqwCAuzBnpA6IrsuBDh2cP3xU=; b=StYu8cZyPZlPGtVLY1U/4H5tWVFNwFhSI/PeHzD1Cb0PoAqc/Ar91teF7wbQklGHdKVTeT oOncv7cj5nEfRXVHlpy6k5ffOPGya1hX6qR+POowOtvnDl5PYCb897pI0N6+PvLQtLY4IF 3EsGx+//jtzJTUH2Jc3cSNSe8lXhmzLuScmbMh5HSyxthx9aU3acZfUNVSdK9x1ks1AAMy o7e+C3DMiHx5RlHPgaU9BbCUv+GvAu+4bhoc7Je5gkLZuEiPpYMHUYU8pylURBGDqzX1dJ qsVTuNlabFjXVzDb4dLFBBWbmL39zwts3el8IPNJlVy9OvBIC8m6Utnz6vnl9A== From: michael.opdenacker@bootlin.com To: docs@lists.yoctoproject.org Cc: Michael Opdenacker Subject: [mickledore][PATCH 4/9] dev-manual: new-recipe.rst: replace reference to wiki Date: Thu, 5 Oct 2023 22:04:48 +0200 Message-Id: <20231005200453.2873299-4-michael.opdenacker@bootlin.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20231005200453.2873299-1-michael.opdenacker@bootlin.com> References: <20231005200453.2873299-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 ; Thu, 05 Oct 2023 20:05:13 -0000 X-Groupsio-URL: https://lists.yoctoproject.org/g/docs/message/4322 From: Michael Opdenacker Signed-off-by: Michael Opdenacker --- documentation/dev-manual/new-recipe.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/documentation/dev-manual/new-recipe.rst b/documentation/dev-manual/new-recipe.rst index 39ee9683b0..a330a8f8c6 100644 --- a/documentation/dev-manual/new-recipe.rst +++ b/documentation/dev-manual/new-recipe.rst @@ -1442,9 +1442,9 @@ doing the following: Following Recipe Style Guidelines ================================= -When writing recipes, it is good to conform to existing style -guidelines. The :oe_wiki:`OpenEmbedded Styleguide ` wiki page -provides rough guidelines for preferred recipe style. +When writing recipes, it is good to conform to existing style guidelines. +See the ":doc:`../contributor-guide/recipe-style-guide`" in the Yocto Project +and OpenEmbedded Contributor Guide for reference. It is common for existing recipes to deviate a bit from this style. However, aiming for at least a consistent style is a good idea. Some From patchwork Thu Oct 5 20:04:49 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Michael Opdenacker X-Patchwork-Id: 31740 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 60F27E93713 for ; Thu, 5 Oct 2023 20:05:13 +0000 (UTC) Received: from relay5-d.mail.gandi.net (relay5-d.mail.gandi.net [217.70.183.197]) by mx.groups.io with SMTP id smtpd.web11.25999.1696536304864439496 for ; Thu, 05 Oct 2023 13:05:05 -0700 Authentication-Results: mx.groups.io; dkim=pass header.i=@bootlin.com header.s=gm1 header.b=BDvqDlRD; spf=pass (domain: bootlin.com, ip: 217.70.183.197, mailfrom: michael.opdenacker@bootlin.com) Received: by mail.gandi.net (Postfix) with ESMTPSA id 340711C000C; Thu, 5 Oct 2023 20:05:03 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bootlin.com; s=gm1; t=1696536303; 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=BV8unj2mtAKrhg0bNHxTMXIJFZqg4GZs3Ulv9x1Ag4c=; b=BDvqDlRDhf8gpT7ieUNhNK3WBpdjgU7LrHCI4ki810I3dxOL8EjBXi/45dIm3naVchCtqu YN17c93D447B/hQFzpr33XSEoSR18mMRnIzVm8TwULKiigE+dSwZSFhsEwPWCez/xlNB9w EAVvmbTXw9cIuTDcFkNWVJA6A1B58gMIXQ+DclAVk4IsrdUPnZgjPOtWwERe+JmpVYH7tr tnQiU2tttu0wuqChlNc5fqaQF1CM+Oz2CqEHiBF+Je5yqbPw1fp5xulMtyPDzLBD6ZtX1D xsMp3F55Xz7STTEbfcin3Ip5xRf0rtzf3wHZEkLxFBxURgNulhnD6q8+0SOKRA== From: michael.opdenacker@bootlin.com To: docs@lists.yoctoproject.org Cc: Michael Opdenacker , Roland Hieber Subject: [mickledore][PATCH 5/9] contributor-guide: recipe-style-guide: add more patch tagging examples Date: Thu, 5 Oct 2023 22:04:49 +0200 Message-Id: <20231005200453.2873299-5-michael.opdenacker@bootlin.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20231005200453.2873299-1-michael.opdenacker@bootlin.com> References: <20231005200453.2873299-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 ; Thu, 05 Oct 2023 20:05:13 -0000 X-Groupsio-URL: https://lists.yoctoproject.org/g/docs/message/4323 From: Michael Opdenacker From: Roland Hieber Signed-off-by: Roland Hieber Reviewed-by: Michael Opdenacker --- .../contributor-guide/recipe-style-guide.rst | 21 ++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/documentation/contributor-guide/recipe-style-guide.rst b/documentation/contributor-guide/recipe-style-guide.rst index b63172bd77..7906e5e5d9 100644 --- a/documentation/contributor-guide/recipe-style-guide.rst +++ b/documentation/contributor-guide/recipe-style-guide.rst @@ -336,7 +336,10 @@ the status should be changed to ``Submitted [where]``, and an additional ``Signed-off-by:`` line should be added to the patch by the person claiming responsibility for upstreaming. -For example, if the patch has been submitted upstream:: +Examples +-------- + +Here's an example of a patch that has been submitted upstream:: rpm: Adjusted the foo setting in bar @@ -351,3 +354,19 @@ For example, if the patch has been submitted upstream:: A future update can change the value to ``Accepted`` or ``Denied`` as appropriate. + +Another example of a patch that is specific to OpenEmbedded:: + + Do not treat warnings as errors + + There are additional warnings found with musl which are + treated as errors and fails the build, we have more combinations + than upstream supports to handle. + + Upstream-Status: Inappropriate [oe specific] + +Here's a patch that has been backported from an upstream commit:: + + include missing sys/file.h for LOCK_EX + + Upstream-Status: Backport [https://github.com/systemd/systemd/commit/ac8db36cbc26694ee94beecc8dca208ec4b5fd45] From patchwork Thu Oct 5 20:04:50 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Michael Opdenacker X-Patchwork-Id: 31739 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 68391E93715 for ; Thu, 5 Oct 2023 20:05:13 +0000 (UTC) Received: from relay5-d.mail.gandi.net (relay5-d.mail.gandi.net [217.70.183.197]) by mx.groups.io with SMTP id smtpd.web10.25926.1696536305437314719 for ; Thu, 05 Oct 2023 13:05:05 -0700 Authentication-Results: mx.groups.io; dkim=pass header.i=@bootlin.com header.s=gm1 header.b=HGSvD7GH; spf=pass (domain: bootlin.com, ip: 217.70.183.197, mailfrom: michael.opdenacker@bootlin.com) Received: by mail.gandi.net (Postfix) with ESMTPSA id CA4101C0005; Thu, 5 Oct 2023 20:05:03 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bootlin.com; s=gm1; t=1696536304; 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=OCJcfS/QQUUN3tBPM13p7JE+bNQuQ70K7+63p1dk6TU=; b=HGSvD7GH0HH3G0aLILwtcJYnvrJ/7Kq+cQt76vBBxo2LeI8OAhJczXdJ9RbIIOt9SUEBIw evp5cwO3EsDdPPGrmVHM5e8PleNfuSF4+GOTH5WNwQ0WmHSuSKulkFuWou2HFxnts6rzwE +WeOUNbLgwQKT1/IFIU2q4fNA9g31TxR5n8cbOSb0dmF3eztetAHvw7eiCEiXTPw9SF7U/ pIZJtDyFQ9WAJtKLT8Xn1+h5d5gxf0sbBg6WbsZ1YI9mZ6UDlv8AL5J/g+ksGZUt8mdCR0 S1dFAVRDfOdKTzi6DAZENajMR2/ILbV+xblHf79A8c+dgLQR+ENO+cidT5goPQ== From: michael.opdenacker@bootlin.com To: docs@lists.yoctoproject.org Cc: Michael Opdenacker , Roland Hieber Subject: [mickledore][PATCH 6/9] contributor-guide: recipe-style-guide: add section about CVE patches Date: Thu, 5 Oct 2023 22:04:50 +0200 Message-Id: <20231005200453.2873299-6-michael.opdenacker@bootlin.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20231005200453.2873299-1-michael.opdenacker@bootlin.com> References: <20231005200453.2873299-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 ; Thu, 05 Oct 2023 20:05:13 -0000 X-Groupsio-URL: https://lists.yoctoproject.org/g/docs/message/4324 From: Michael Opdenacker From: Roland Hieber This was previously included in the OpenEmbedded wiki page [1], but was not ported along with the rest in commit 95c9a1e1e78bbfb82ade (2023-09-12, Michael Opdenacker: "contributor-guide: recipe-style-guide: add Upstream-Status"). [1]: https://www.openembedded.org/index.php?title=Commit_Patch_Message_Guidelines&oldid=10935 Group the examples in their own sections (but name it differently from any other section in this document so that sphinx doesn't generate a warning about duplicate labels). Signed-off-by: Roland Hieber Reviewed-by: Michael Opdenacker --- .../contributor-guide/recipe-style-guide.rst | 25 +++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/documentation/contributor-guide/recipe-style-guide.rst b/documentation/contributor-guide/recipe-style-guide.rst index 7906e5e5d9..5cbcb23b3a 100644 --- a/documentation/contributor-guide/recipe-style-guide.rst +++ b/documentation/contributor-guide/recipe-style-guide.rst @@ -370,3 +370,28 @@ Here's a patch that has been backported from an upstream commit:: include missing sys/file.h for LOCK_EX Upstream-Status: Backport [https://github.com/systemd/systemd/commit/ac8db36cbc26694ee94beecc8dca208ec4b5fd45] + +CVE patches +=========== + +In order to have a better control of vulnerabilities, patches that fix CVEs must +contain a ``CVE:`` tag. This tag list all CVEs fixed by the patch. If more than +one CVE is fixed, separate them using spaces. + +CVE Examples +------------ + +This should be the header of patch that fixes :cve:`2015-8370` in GRUB2:: + + grub2: Fix CVE-2015-8370 + + [No upstream tracking] -- https://bugzilla.redhat.com/show_bug.cgi?id=1286966 + + Back to 28; Grub2 Authentication + + Two functions suffer from integer underflow fault; the grub_username_get() and grub_password_get()located in + grub-core/normal/auth.c and lib/crypto.c respectively. This can be exploited to obtain a Grub rescue shell. + + Upstream-Status: Backport [http://git.savannah.gnu.org/cgit/grub.git/commit/?id=451d80e52d851432e109771bb8febafca7a5f1f2] + CVE: CVE-2015-8370 + Signed-off-by: Joe Developer From patchwork Thu Oct 5 20:04:51 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Michael Opdenacker X-Patchwork-Id: 31743 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 6EBC1E93714 for ; Thu, 5 Oct 2023 20:05:13 +0000 (UTC) Received: from relay3-d.mail.gandi.net (relay3-d.mail.gandi.net [217.70.183.195]) by mx.groups.io with SMTP id smtpd.web11.26001.1696536306944976855 for ; Thu, 05 Oct 2023 13:05:07 -0700 Authentication-Results: mx.groups.io; dkim=pass header.i=@bootlin.com header.s=gm1 header.b=UsrqSv/W; spf=pass (domain: bootlin.com, ip: 217.70.183.195, mailfrom: michael.opdenacker@bootlin.com) Received: by mail.gandi.net (Postfix) with ESMTPSA id CC45760004; Thu, 5 Oct 2023 20:05:04 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bootlin.com; s=gm1; t=1696536305; 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=qQWkpX1hLHnF39Qu2UJAgqFh5fW2f+4kbXVmBQwVHcM=; b=UsrqSv/WR2d7SP4I5fNoAZF881ji6376XFxhKJ9ic4XKpozwLE38pyzCrd7s6pM6MbwnqD Ln0cr3jOkeI14rwZauejIh7n0nQnE9wasCUC9bgpgDsxSGXxBVqluf0cN/Wm7WqzCG3ml+ 7MMkaopu/ovQSixoVJtoM417IC6NkVgipFaXteWNJA2Z8kQn7jHkTqU9K8es+EX9r427Ry RwXLHJuumYul9xS7D2bxBD5/zD+uEfSb6uOR5E/iofRodxzXhzhH1R9Yi9+FweACA4Zdj1 Az25tanFAK/G4/KVTRcOkIgmdbtrqsFigDG+/ee1LMpa9Z3t80DVo2iM4vojqQ== From: michael.opdenacker@bootlin.com To: docs@lists.yoctoproject.org Cc: Michael Opdenacker , Alexander Kanavin , Roland Hieber Subject: [mickledore][PATCH 7/9] contributor-guide: discourage marking patches as Inappropriate Date: Thu, 5 Oct 2023 22:04:51 +0200 Message-Id: <20231005200453.2873299-7-michael.opdenacker@bootlin.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20231005200453.2873299-1-michael.opdenacker@bootlin.com> References: <20231005200453.2873299-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 ; Thu, 05 Oct 2023 20:05:13 -0000 X-Groupsio-URL: https://lists.yoctoproject.org/g/docs/message/4325 From: Michael Opdenacker From: Roland Hieber It was never really clear what all those reasons really meant, and every patch submitted upstream liftens the maintenance on the Yocto side. So remove the current list, and replace it with two reasons in which an upstream submission likely won't benefit the upstream project. Suggested-by: Alexander Kanavin Signed-off-by: Roland Hieber Reviewed-by: Michael Opdenacker --- .../contributor-guide/recipe-style-guide.rst | 30 +++++++++---------- 1 file changed, 14 insertions(+), 16 deletions(-) diff --git a/documentation/contributor-guide/recipe-style-guide.rst b/documentation/contributor-guide/recipe-style-guide.rst index 5cbcb23b3a..7e336a0424 100644 --- a/documentation/contributor-guide/recipe-style-guide.rst +++ b/documentation/contributor-guide/recipe-style-guide.rst @@ -314,22 +314,20 @@ following status strings: ``Inappropriate [reason]`` The patch is not appropriate for upstream, include a brief reason on the - same line enclosed with ``[]``. The reason can be: - - - ``not author`` (you are not the author and do not intend to upstream this, - the source must be listed in the comments) - - ``native`` - - ``licensing`` - - ``configuration`` - - ``enable feature`` - - ``disable feature`` - - ``bugfix`` (add bug URL here) - - ``embedded specific`` - - ``other`` (give details in comments) - -The various ``Inappropriate [reason]`` status items are meant to indicate that -the person responsible for adding this patch to the system does not intend to -upstream the patch for a specific reason. + same line enclosed with ``[]``. In the past, there were several different + reasons not to submit patches upstream, but we have to consider that every + non-upstreamed patch means a maintainance burden for recipe maintainers. + Currently, the only reasons to mark patches as inappropriate for upstream + submission are: + + - ``oe specific``: the issue is specific to how OpenEmbedded performs builds + or sets things up at runtime, and can be resolved only with a patch that + is not however relevant or appropriate for general upstream submission. + - ``upstream ticket ``: the issue is not specific to Open-Embedded + and should be fixed upstream, but the patch in its current form is not + suitable for merging upstream, and the author lacks sufficient expertise + to develop a proper patch. Instead the issue is handled via a bug report + (include link). Of course, if another person later takes care of submitting this patch upstream, the status should be changed to ``Submitted [where]``, and an additional From patchwork Thu Oct 5 20:04:52 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Michael Opdenacker X-Patchwork-Id: 31744 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 7BDB1E9371B for ; Thu, 5 Oct 2023 20:05:13 +0000 (UTC) Received: from relay1-d.mail.gandi.net (relay1-d.mail.gandi.net [217.70.183.193]) by mx.groups.io with SMTP id smtpd.web10.25927.1696536307167703925 for ; Thu, 05 Oct 2023 13:05:07 -0700 Authentication-Results: mx.groups.io; dkim=pass header.i=@bootlin.com header.s=gm1 header.b=HRUti+gM; spf=pass (domain: bootlin.com, ip: 217.70.183.193, mailfrom: michael.opdenacker@bootlin.com) Received: by mail.gandi.net (Postfix) with ESMTPSA id 8FA38240002; Thu, 5 Oct 2023 20:05:05 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bootlin.com; s=gm1; t=1696536305; 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=X/pF+3FbmgRAhHX5/6ZglyOj6qnU3kX5YLilRmR9a5c=; b=HRUti+gMUQBiDtTUCGobKNyn/64LAoC9zzb2q1L0Kz5puyJfMXk0lw+L53O5/WHECi7o2R BAU3XqQsZuGSJsBRFploYG3kL4qXEbZrf2fY3Q8KKDxkBgeYx9BmLUivJST0DD1JwaCx/4 8y01bBEZWjtCMx+PPYLf8f5Tu86OLFs9HXLhJNCG5amB0YlYB+0eUJVZIQzBUitYMrnLIL JagoKZLNkS8ZHo7JyPtSkM9q91seltkamEe1sYVOqvYj+xPrW0E4hFrWumL4XLLlWc+FZH cA9/jYue9ArUspsWqbAosD8UiZFUXePTKIdLezLuG/F9OOx0zFM/b4Zsfynh6g== From: michael.opdenacker@bootlin.com To: docs@lists.yoctoproject.org Cc: Michael Opdenacker , Roland Hieber Subject: [mickledore][PATCH 8/9] contributor-guide: deprecate "Accepted" patch status Date: Thu, 5 Oct 2023 22:04:52 +0200 Message-Id: <20231005200453.2873299-8-michael.opdenacker@bootlin.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20231005200453.2873299-1-michael.opdenacker@bootlin.com> References: <20231005200453.2873299-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 ; Thu, 05 Oct 2023 20:05:13 -0000 X-Groupsio-URL: https://lists.yoctoproject.org/g/docs/message/4326 From: Michael Opdenacker From: Roland Hieber This is in accordance with the gatesgarth Release Notes: > In the ``Upstream-Status`` header convention for patches, > ``Accepted`` has | been replaced with ``Backport`` as these almost > always mean the same thing i.e. the patch is already upstream and > may need to be removed in a future recipe upgrade. If you are adding > these headers to your own patches then use Backport to indicate that > the patch has been sent upstream. Suggested-by: Michael Opdenacker Signed-off-by: Roland Hieber Reviewed-by: Michael Opdenacker --- .../contributor-guide/recipe-style-guide.rst | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/documentation/contributor-guide/recipe-style-guide.rst b/documentation/contributor-guide/recipe-style-guide.rst index 7e336a0424..e03b8ff2ba 100644 --- a/documentation/contributor-guide/recipe-style-guide.rst +++ b/documentation/contributor-guide/recipe-style-guide.rst @@ -292,13 +292,10 @@ following status strings: Submitted to upstream, waiting for approval. Optionally include where it was submitted, such as the author, mailing list, etc. -``Accepted`` - Accepted in upstream, expect it to be removed at next update, include - expected version info. - -``Backport`` - Backported from new upstream version, because we are at a fixed version, - include upstream version info. +``Backport [version]`` + Accepted upstream and included in the next release, or backported from newer + upstream version, because we are at a fixed version. + Include upstream version info (e.g. commit ID or next expected version). ``Denied`` Not accepted by upstream, include reason in patch. @@ -350,7 +347,7 @@ Here's an example of a patch that has been submitted upstream:: Signed-off-by: Joe Developer -A future update can change the value to ``Accepted`` or ``Denied`` as +A future update can change the value to ``Backport`` or ``Denied`` as appropriate. Another example of a patch that is specific to OpenEmbedded:: From patchwork Thu Oct 5 20:04:53 2023 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Michael Opdenacker X-Patchwork-Id: 31742 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 7BD08E9371A for ; Thu, 5 Oct 2023 20:05:13 +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.web10.25929.1696536310125948407 for ; Thu, 05 Oct 2023 13:05:10 -0700 Authentication-Results: mx.groups.io; dkim=pass header.i=@bootlin.com header.s=gm1 header.b=n4zcSSxv; spf=pass (domain: bootlin.com, ip: 217.70.183.198, mailfrom: michael.opdenacker@bootlin.com) Received: by mail.gandi.net (Postfix) with ESMTPSA id 8C441C000A; Thu, 5 Oct 2023 20:05:06 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=bootlin.com; s=gm1; t=1696536307; 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=CLmesjVkNE0LwzvSiL9Xt5Jfae9mIWCRGPj45cQTtug=; b=n4zcSSxvI4VqY1ktirokNlT84ZP7aVjmE6IKJmUjDEs/Xn02DEn0D+83vJHn3LvFVBL+fv nbBgUj/vJzkn+RZ0PVqehWUw/Zp3mBsDQFiWH9WZlvLV+kVnwpgl+fsXeKuxbBeq49vVUF cSYvV7K1auGP67tTS+r7EG80FJxHquWoqNRok7j0gGAIJmBs+0MEZ5eHe160oB5Flgou+j aFcSQSsdpNd8qNZKLV1cY6nCyH6mHqXAjK9MM/aUuV2BI9QyPY+ZYmF3bjnDMJ6RG2NRQW rPIluIpRFPJmLaIwebkDRNAtGkQODqKwFffQwtfe9/29/w7O22EM9xNm75gDjQ== From: michael.opdenacker@bootlin.com To: docs@lists.yoctoproject.org Cc: Michael Opdenacker , Alexander Kanavin , Roland Hieber Subject: [mickledore][PATCH 9/9] contributor-guide: style-guide: discourage using Pending patch status Date: Thu, 5 Oct 2023 22:04:53 +0200 Message-Id: <20231005200453.2873299-9-michael.opdenacker@bootlin.com> X-Mailer: git-send-email 2.34.1 In-Reply-To: <20231005200453.2873299-1-michael.opdenacker@bootlin.com> References: <20231005200453.2873299-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 ; Thu, 05 Oct 2023 20:05:13 -0000 X-Groupsio-URL: https://lists.yoctoproject.org/g/docs/message/4327 From: Michael Opdenacker From: Roland Hieber Suggested-by: Michael Opdenacker Suggested-by: Alexander Kanavin Signed-off-by: Roland Hieber Reviewed-by: Michael Opdenacker --- documentation/contributor-guide/recipe-style-guide.rst | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/documentation/contributor-guide/recipe-style-guide.rst b/documentation/contributor-guide/recipe-style-guide.rst index e03b8ff2ba..a005aa3247 100644 --- a/documentation/contributor-guide/recipe-style-guide.rst +++ b/documentation/contributor-guide/recipe-style-guide.rst @@ -286,7 +286,14 @@ Then, you should also add an ``Upstream-Status:`` tag containing one of the following status strings: ``Pending`` - No determination has been made yet or not yet submitted to upstream. + No determination has been made yet, or patch has not yet been submitted to + upstream. + + Keep in mind that every patch submitted upstream reduces the maintainance + burden in OpenEmbedded and Yocto Project in the long run, so this patch + status should only be used in exceptional cases if there are genuine + obstacles to submitting a patch upstream; the reason for that should be + included in the patch. ``Submitted [where]`` Submitted to upstream, waiting for approval. Optionally include where