From d2b0ce01ba55cb32c01867aa93110cf5f72a07e1 Mon Sep 17 00:00:00 2001 From: Vincent Fazio Date: Mon, 3 Apr 2023 09:41:03 -0500 Subject: [PATCH] docs/manual: rewrite section for upstream documentation 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 Signed-off-by: Yann E. MORIN (cherry picked from commit 5b00b40a05437e1042b25c097b977d5a26bdee1d) Signed-off-by: Peter Korsgaard --- 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: +Upstream: --------------- -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: +Upstream: --------------- -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 +--------------- + +Adding this documentation helps streamline the patch review process during +package version updates. \ No newline at end of file