* [PATCH] docs: process: Add base-commit trailer usage
@ 2019-10-30 14:00 Konstantin Ryabitsev
2019-11-07 20:00 ` Jonathan Corbet
0 siblings, 1 reply; 3+ messages in thread
From: Konstantin Ryabitsev @ 2019-10-30 14:00 UTC (permalink / raw)
To: Jonathan Corbet, linux-doc; +Cc: linux-kernel
One of the recurring complaints from both maintainers and CI system
operators is that performing git-am on received patches is difficult
without knowing the parent object in the git history on which the
patches are based. Without this information, there is a high likelihood
that git-am will fail due to conflicts, which is particularly
frustrating to CI operators.
Git versions starting with v2.9.0 are able to automatically include
base-commit information using the --base flag of git-format-patch.
Document this usage in process/submitting-patches, and add the rationale
for its inclusion, plus instructions for those not using git on where
the "base-commit:" trailer should go.
Signed-off-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org>
---
Documentation/process/submitting-patches.rst | 53 +++++++++++++++++++-
1 file changed, 52 insertions(+), 1 deletion(-)
diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst
index fb56297f70dc..ba5e944c7a63 100644
--- a/Documentation/process/submitting-patches.rst
+++ b/Documentation/process/submitting-patches.rst
@@ -782,7 +782,58 @@ helpful, you can use the https://lkml.kernel.org/ redirector (e.g., in
the cover email text) to link to an earlier version of the patch series.
-16) Sending ``git pull`` requests
+16) 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.
+
+If you are using ``git format-patch`` to generate your patches, you can
+automatically include the base tree information in your submission by
+using the ``--base`` flag. The easiest and most convenient way to use
+this option is with topical branches::
+
+ $ git checkout -t -b my-topical-branch master
+ Branch 'my-topical-branch' set up to track local branch 'master'.
+ Switched to a new branch 'my-topical-branch'
+
+ [perform your edits and commits]
+
+ $ git format-patch --base=auto --cover-letter -o outgoing/ master
+ outgoing/0000-cover-letter.patch
+ outgoing/0001-First-Commit.patch
+ outgoing/...
+
+When you open ``outgoing/0000-cover-letter.patch`` for editing, you will
+notice that it will have the ``base-commit:`` trailer at the very
+bottom, which provides the reviewer and the CI tools enough information
+to properly perform ``git am`` without worrying about conflicts::
+
+ $ git checkout -b patch-review [base-commit-id]
+ Switched to a new branch 'patch-review'
+ $ git am patches.mbox
+ Applying: First Commit
+ Applying: ...
+
+Please see ``man git-format-patch`` for more information about this
+option.
+
+.. note::
+
+ The ``--base`` feature was introduced in git version 2.9.0.
+
+If you are not using git to format your patches, you can still include
+the same ``base-commit`` trailer to indicate the commit hash of the tree
+on which your work is based. You should add it either in the cover
+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.
+
+
+17) Sending ``git pull`` requests
---------------------------------
If you have a series of patches, it may be most convenient to have the
base-commit: 23fdb198ae81f47a574296dab5167c5e136a02ba
--
2.21.0
^ permalink raw reply related [flat|nested] 3+ messages in thread
* Re: [PATCH] docs: process: Add base-commit trailer usage
2019-10-30 14:00 [PATCH] docs: process: Add base-commit trailer usage Konstantin Ryabitsev
@ 2019-11-07 20:00 ` Jonathan Corbet
2019-11-07 20:05 ` Konstantin Ryabitsev
0 siblings, 1 reply; 3+ messages in thread
From: Jonathan Corbet @ 2019-11-07 20:00 UTC (permalink / raw)
To: Konstantin Ryabitsev; +Cc: linux-doc, linux-kernel
On Wed, 30 Oct 2019 10:00:50 -0400
Konstantin Ryabitsev <konstantin@linuxfoundation.org> wrote:
> One of the recurring complaints from both maintainers and CI system
> operators is that performing git-am on received patches is difficult
> without knowing the parent object in the git history on which the
> patches are based. Without this information, there is a high likelihood
> that git-am will fail due to conflicts, which is particularly
> frustrating to CI operators.
>
> Git versions starting with v2.9.0 are able to automatically include
> base-commit information using the --base flag of git-format-patch.
> Document this usage in process/submitting-patches, and add the rationale
> for its inclusion, plus instructions for those not using git on where
> the "base-commit:" trailer should go.
>
> Signed-off-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org>
I really wish we could find a way to make submitting-patches.rst shorter
rather than longer - it's a lot for a first-time submitter to work
through. But this is useful information, so I've applied it.
Thanks,
jon
^ permalink raw reply [flat|nested] 3+ messages in thread
* Re: [PATCH] docs: process: Add base-commit trailer usage
2019-11-07 20:00 ` Jonathan Corbet
@ 2019-11-07 20:05 ` Konstantin Ryabitsev
0 siblings, 0 replies; 3+ messages in thread
From: Konstantin Ryabitsev @ 2019-11-07 20:05 UTC (permalink / raw)
To: Jonathan Corbet; +Cc: linux-doc, linux-kernel
On Thu, Nov 07, 2019 at 01:00:52PM -0700, Jonathan Corbet wrote:
>On Wed, 30 Oct 2019 10:00:50 -0400
>Konstantin Ryabitsev <konstantin@linuxfoundation.org> wrote:
>
>> One of the recurring complaints from both maintainers and CI system
>> operators is that performing git-am on received patches is difficult
>> without knowing the parent object in the git history on which the
>> patches are based. Without this information, there is a high likelihood
>> that git-am will fail due to conflicts, which is particularly
>> frustrating to CI operators.
>>
>> Git versions starting with v2.9.0 are able to automatically include
>> base-commit information using the --base flag of git-format-patch.
>> Document this usage in process/submitting-patches, and add the rationale
>> for its inclusion, plus instructions for those not using git on where
>> the "base-commit:" trailer should go.
>>
>> Signed-off-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org>
>
>I really wish we could find a way to make submitting-patches.rst shorter
>rather than longer - it's a lot for a first-time submitter to work
>through. But this is useful information, so I've applied it.
I think that's the eventual goal, and I'm happy to take a stab at making
this page shorter. The easiest would be to rewrite that page so that it
only includes git-specific instructions. I think at this point in time
we can safely say that anyone who need guidance on submitting patches
would be already using git -- anyone who doesn't use git for that
process doesn't really need this doc anyway.
I'll work on an RFC patch to slim this doc down.
-K
^ permalink raw reply [flat|nested] 3+ messages in thread
end of thread, other threads:[~2019-11-07 20:05 UTC | newest]
Thread overview: 3+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2019-10-30 14:00 [PATCH] docs: process: Add base-commit trailer usage Konstantin Ryabitsev
2019-11-07 20:00 ` Jonathan Corbet
2019-11-07 20:05 ` Konstantin Ryabitsev
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).