docs: process: Add base-commit trailer usage
Subsystems (2)
PATCH 1/1 docs: process: Add base-commit trailer usage
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.
--- Documentation/process/submitting-patches.rst | 53 +++++++++++++++++++- 1 file changed, 52 insertions(+), 1 deletion(-)
Documentation/process/submitting-patches.rst +52 -1
@@ -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
Signature · 1 line
2.21.0
Jonathan Corbet
maintainerQuoted 7 lines · On Wed, 30 Oct 2019 10:00:50 -0400 Konstantin Ryabitsev…
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.
Quoted 7 lines
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 <[email protected]>
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
Quoted 16 lines · Jonathan Corbet
Quoted 13 lines · On Wed, 30 Oct 2019 10:00:50 -0400 Konstantin Ryabitsev…
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.
Quoted 5 lines
Quoted 1 line
Signed-off-by Konstantin Ryabitsev <[email protected]>I really wish we could find a way to make
submitting-patches.rstshorter 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