[Buildroot] [git commit branch/2023.02.x] docs/manual: rewrite section for upstream documentation

[Peter Korsgaard]

commit: https://git.buildroot.net/buildroot/commit/?id=d2b0ce01ba55cb32c01867aa93110cf5f72a07e1
branch: https://git.buildroot.net/buildroot/commit/?id=refs/heads/2023.02.x

Previously, the documentation only requested links to upstream commits
when backporting patches.

Based on a mailing list discussion [0], patches should, when possible
and when approriate, provide a link as evidence that the patch has been
submitted upstream.

The motivation is that hopefully the patch gets applied to upstream at
some point reducing the long term maintenance burden within Buildroot.
This also makes future patch review on subsequent package version bumps
more streamlined.

For patches that are unique to BR and do not apply to the upstream
repository, patches should have a comment explaining why they do not
apply upstream.

[0] https://lists.buildroot.org/pipermail/buildroot/2023-March/666000.html

Signed-off-by: Vincent Fazio <vfazio at gmail.com>
Signed-off-by: Yann E. MORIN <yann.morin.1998 at free.fr>
(cherry picked from commit 5b00b40a05437e1042b25c097b977d5a26bdee1d)
Signed-off-by: Peter Korsgaard <peter at korsgaard.com>
---
 docs/manual/patch-policy.txt | 35 ++++++++++++++++++++++++-----------
 1 file changed, 24 insertions(+), 11 deletions(-)

diff --git a/docs/manual/patch-policy.txt b/docs/manual/patch-policy.txt
index 063ef984d8..dc35132ecf 100644
--- a/docs/manual/patch-policy.txt
+++ b/docs/manual/patch-policy.txt
@@ -144,24 +144,37 @@ AC_PROG_MAKE_SET
 +AM_CONDITIONAL([CXX_WORKS], [test "x$rw_cv_prog_cxx_works" = "xyes"])
 ---------------
 
-=== Integrating patches found on the Web
+=== Additional patch documentation
 
-When integrating a patch of which you are not the author, you have to
-add a few things in the header of the patch itself.
+Ideally, all patches should document an upstream patch or patch submission, when
+applicable, via the +Upstream+ trailer.
 
-Depending on whether the patch has been obtained from the project
-repository itself, or from somewhere on the web, add one of the
-following tags:
+When backporting an upstream patch that has been accepted into mainline, it is
+preferred that the URL to the commit is referenced:
 
 ---------------
-Backported from: <some commit id>
+Upstream: <URL to upstream commit>
 ---------------
 
-or
+If a new issue is identified in Buildroot and upstream is generally affected by 
+the issue (it's not a Buildroot specific issue), users should submit the patch
+upstream and provide a link to that submission when possible:
 
 ---------------
-Fetch from: <some url>
+Upstream: <URL to upstream mailing list submission or merge request>
 ---------------
 
-It is also sensible to add a few words about any changes to the patch
-that may have been necessary.
+Patches that have been submitted but were denied upstream should note that and
+include comments about why the patch is being used despite the upstream status.
+
+Note: in any of the above scenarios, it is also sensible to add a few words
+about any changes to the patch that may have been necessary.
+
+If a patch does not apply upstream then this should be noted with a comment:
+
+---------------
+Upstream: N/A <additional information about why patch is Buildroot specific>
+---------------
+
+Adding this documentation helps streamline the patch review process during
+package version updates.
\ No newline at end of file