diff mbox series

contributor-guide: recipe-style-guide: add Upstream-Status

Message ID 20230913082133.487970-1-michael.opdenacker@bootlin.com
State New
Headers show
Series contributor-guide: recipe-style-guide: add Upstream-Status | expand

Commit Message

Michael Opdenacker Sept. 13, 2023, 8:21 a.m. UTC
From: Michael Opdenacker <michael.opdenacker@bootlin.com>

Signed-off-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
 .../contributor-guide/recipe-style-guide.rst  | 81 +++++++++++++++++++
 1 file changed, 81 insertions(+)
diff mbox series


diff --git a/documentation/contributor-guide/recipe-style-guide.rst b/documentation/contributor-guide/recipe-style-guide.rst
index a0d513e8e9..99105179a6 100644
--- a/documentation/contributor-guide/recipe-style-guide.rst
+++ b/documentation/contributor-guide/recipe-style-guide.rst
@@ -255,3 +255,84 @@  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.
+Patch Upstream Status
+In order to keep track of patches applied by recipes and ultimately reduce the
+number of patches that need maintaining, the OpenEmbedded build system
+requires information about the upstream status of each patch.
+In its description, each patch should provide detailed information about the
+bug that it addresses, such as the URL in a bug tracking system and links
+to relevant mailing list archives.
+Then, you should also add an ``Upstream-Status:`` tag containing one of the
+following status strings:
+   No determination has been made yet or not yet submitted to upstream.
+``Submitted [where]``
+   Submitted to upstream, waiting for approval. Optionally include where
+   it was submitted, such as the author, mailing list, etc.
+   Accepted in upstream, expect it to be removed at next update, include
+   expected version info.
+   Backported from new upstream version, because we are at a fixed version,
+   include upstream version info.
+   Not accepted by upstream, include reason in patch.
+``Inactive-Upstream [lastcommit: when (and/or) lastrelease: when]``
+   The upstream is no longer available. This typically means a defunct project
+   where no activity has happened for a long time --- measured in years. To make
+   that judgement, it is recommended to look at not only when the last release
+   happened, but also when the last commit happened, and whether newly made bug
+   reports and merge requests since that time receive no reaction. It is also
+   recommended to add to the patch description any relevant links where the
+   inactivity can be clearly seen.
+``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.
+Of course, if another person later takes care of submitting this patch upstream,
+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::
+   rpm: Adjusted the foo setting in bar
+   [RPM Ticket #65] -- http://rpm5.org/cvs/tktview?tn=65,5
+   The foo setting in bar was decreased from X to X-50% in order to
+   ensure we don't exhaust all system memory with foobar threads.
+   Upstream-Status: Submitted [rpm5-devel@rpm5.org]
+   Signed-off-by: Joe Developer <joe.developer@example.com>
+A future update can change the value to ``Accepted`` or ``Denied`` as