[PATCH] docs: submitting-patches: improve the base commit explanation

[PATCH] docs: submitting-patches: improve the base commit explanation

[Borislav Petkov]

From: "Borislav Petkov (AMD)" <bp@alien8.de>

After receiving a second patchset this week without knowing which tree
it applies on and trying to apply it on the obvious ones and failing,
make sure the base tree information which needs to be supplied in the
0th message of the patchset is spelled out more explicitly.

Also, make the formulations stronger as this really is a requirement and
not only a useful thing anymore.

Signed-off-by: Borislav Petkov (AMD) <bp@alien8.de>
---
 Documentation/process/submitting-patches.rst | 15 +++++++++++----
 1 file changed, 11 insertions(+), 4 deletions(-)

diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst
index 86d346bcb8ef..66029999b587 100644
--- a/Documentation/process/submitting-patches.rst
+++ b/Documentation/process/submitting-patches.rst
@@ -790,10 +790,14 @@ Providing base tree information
 -------------------------------
 
 When other developers receive your patches and start the review process,
-it is often useful for them to know where in the tree history they
-should place your work. This is particularly useful for automated CI
-processes that attempt to run a series of tests in order to establish
-the quality of your submission before the maintainer starts the review.
+it is absolutely necessary for them to know what is the base
+commit/branch your work applies on, considering the sheer amount of
+maintainer trees present nowadays. Note again the **T:** entry in the
+MAINTAINERS file explained above.
+
+This is even more important for automated CI processes that attempt to
+run a series of tests in order to establish the quality of your
+submission before the maintainer starts the review.
 
 If you are using ``git format-patch`` to generate your patches, you can
 automatically include the base tree information in your submission by
@@ -836,6 +840,9 @@ letter or in the first patch of the series and it should be placed
 either below the ``---`` line or at the very bottom of all other
 content, right before your email signature.
 
+Make sure that base commit is in an official maintainer/mainline tree
+and not in some internal, accessible only to you tree - otherwise it
+would be worthless.
 
 References
 ----------
-- 
2.42.0.rc0.25.ga82fb66fed25

Re: [PATCH] docs: submitting-patches: improve the base commit explanation

[Kees Cook]

On Wed, Nov 15, 2023 at 06:03:30PM +0100, Borislav Petkov wrote:
> From: "Borislav Petkov (AMD)" <bp@alien8.de>
> 
> After receiving a second patchset this week without knowing which tree
> it applies on and trying to apply it on the obvious ones and failing,
> make sure the base tree information which needs to be supplied in the
> 0th message of the patchset is spelled out more explicitly.
> 
> Also, make the formulations stronger as this really is a requirement and
> not only a useful thing anymore.
> 
> Signed-off-by: Borislav Petkov (AMD) <bp@alien8.de>

Yup, I wonder if making "--base=auto" a default in git might be a good
idea too?

Reviewed-by: Kees Cook <keescook@chromium.org>

-- 
Kees Cook

Re: [PATCH] docs: submitting-patches: improve the base commit explanation

[Laurent Pinchart]

On Wed, Nov 15, 2023 at 09:49:31AM -0800, Kees Cook wrote:
> On Wed, Nov 15, 2023 at 06:03:30PM +0100, Borislav Petkov wrote:
> > From: "Borislav Petkov (AMD)" <bp@alien8.de>
> > 
> > After receiving a second patchset this week without knowing which tree
> > it applies on and trying to apply it on the obvious ones and failing,
> > make sure the base tree information which needs to be supplied in the
> > 0th message of the patchset is spelled out more explicitly.
> > 
> > Also, make the formulations stronger as this really is a requirement and
> > not only a useful thing anymore.
> > 
> > Signed-off-by: Borislav Petkov (AMD) <bp@alien8.de>
> 
> Yup, I wonder if making "--base=auto" a default in git might be a good
> idea too?

When the base of a series is in Linus' tree, or in the corresponding
subsystem maintainer's tree, things are easy, but there are many
situations where the base is a merge of multiple branches (perhaps a
for-next and a fixes branch for instance), or where prerequisites have
been applied manually for one reason or another. This can and should of
course be described in the cover letter, and the submitter should push
and provide a link to a branch that contains the series on top of the
appropriate base (or just a link to the base). This won't help the bots
much though, if they just look at the base tag. Is there a way, or can
we standardize on a way, to indicate where the base can be found ?

> Reviewed-by: Kees Cook <keescook@chromium.org>

-- 
Regards,

Laurent Pinchart

Re: [PATCH] docs: submitting-patches: improve the base commit explanation

[Konstantin Ryabitsev]

On Wed, Nov 15, 2023 at 07:56:32PM +0200, Laurent Pinchart wrote:
> When the base of a series is in Linus' tree, or in the corresponding
> subsystem maintainer's tree, things are easy, but there are many
> situations where the base is a merge of multiple branches (perhaps a
> for-next and a fixes branch for instance), or where prerequisites have
> been applied manually for one reason or another. This can and should of
> course be described in the cover letter, and the submitter should push
> and provide a link to a branch that contains the series on top of the
> appropriate base (or just a link to the base). This won't help the bots
> much though, if they just look at the base tag. Is there a way, or can
> we standardize on a way, to indicate where the base can be found ?

Yes, I suggest we use:

base-repository: <some-canonical-repo-url>

So, a b4-submitted series will have these footers:

change-id: <unique-series-id>
base-commit: <commit-id-or-tag>
base-repository: <canonical-repo-url>

(And then, eventually, there will be series dependency info in the format:

requires: <unique-series-id>:<version>

-K

Re: [PATCH] docs: submitting-patches: improve the base commit explanation

[Borislav Petkov]

On Wed, Nov 15, 2023 at 09:49:31AM -0800, Kees Cook wrote:
> On Wed, Nov 15, 2023 at 06:03:30PM +0100, Borislav Petkov wrote:
> > From: "Borislav Petkov (AMD)" <bp@alien8.de>
> > 
> > After receiving a second patchset this week without knowing which tree
> > it applies on and trying to apply it on the obvious ones and failing,
> > make sure the base tree information which needs to be supplied in the
> > 0th message of the patchset is spelled out more explicitly.
> > 
> > Also, make the formulations stronger as this really is a requirement and
> > not only a useful thing anymore.
> > 
> > Signed-off-by: Borislav Petkov (AMD) <bp@alien8.de>
> 
> Yup, I wonder if making "--base=auto" a default in git might be a good
> idea too?

Not a bad idea. And if not needed, one can simply ignore it when reading
the cover letter.

CCing the git ML for comment/opinions.

Thx.

-- 
Regards/Gruss,
    Boris.

https://people.kernel.org/tglx/notes-about-netiquette

Re: [PATCH] docs: submitting-patches: improve the base commit explanation

[Jonathan Corbet]

Borislav Petkov <bp@alien8.de> writes:

> From: "Borislav Petkov (AMD)" <bp@alien8.de>
>
> After receiving a second patchset this week without knowing which tree
> it applies on and trying to apply it on the obvious ones and failing,
> make sure the base tree information which needs to be supplied in the
> 0th message of the patchset is spelled out more explicitly.
>
> Also, make the formulations stronger as this really is a requirement and
> not only a useful thing anymore.
>
> Signed-off-by: Borislav Petkov (AMD) <bp@alien8.de>
> ---
>  Documentation/process/submitting-patches.rst | 15 +++++++++++----
>  1 file changed, 11 insertions(+), 4 deletions(-)

Applied, thanks.

jon