@@ -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:
+
+``Pending``
+ 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``
+ 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.
+
+``Denied``
+ 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
+appropriate.