[PATCH] Documentation: Document how to get links with git am

[PATCH] Documentation: Document how to get links with git am

[Linus Walleij]

This adds Kees' clever apply hook to the kernel documentation so
it can be easily references when needed.

Cc: Kees Cook <keescook@chromium.org>
Link: https://lists.linuxfoundation.org/pipermail/ksummit-discuss/2019-July/006608.html
Signed-off-by: Linus Walleij <linus.walleij@linaro.org>
---
 .../process/applying-patches-using-git.rst    | 43 +++++++++++++++++++
 Documentation/process/index.rst               |  1 +
 2 files changed, 44 insertions(+)
 create mode 100644 Documentation/process/applying-patches-using-git.rst

diff --git a/Documentation/process/applying-patches-using-git.rst b/Documentation/process/applying-patches-using-git.rst
new file mode 100644
index 000000000000..60955aa62d42
--- /dev/null
+++ b/Documentation/process/applying-patches-using-git.rst
@@ -0,0 +1,43 @@
+.. _applying_patches_using_git:
+
+Applying Patches to the Linux Kernel Using git
+++++++++++++++++++++++++++++++++++++++++++++++
+
+For the most part, using git to apply patches comes down to just following
+the established usage already documented in the git documentation. This is
+pretty intuitive since git was developed initially for Linux kernel
+development.
+
+In some cases the Linux kernel development has special quirks and usage
+patterns that are not an intrinsic part of git.
+
+This file documents some best practices.
+
+
+Creating commit links to lore.kernel.org
+========================================
+
+The web site http://lore.kernel.org is meant as a grand archive of all mail
+list traffic concerning or influencing the kernel development. Storing archives
+of patches here is a recommended practice, and when a maintainer applies a
+patch to a subsystem tree, it is a good idea to provide a Link: tag with a
+reference back to the lore archive so that people that browse the commit
+history can find related discussions and rationale behind a certain change.
+The link tag will look like this:
+
+    Link: https://lore.kernel.org/r/<message-id>
+
+This can be achieved by adding the following hook into your git:
+
+.. code-block:: none
+
+	$ git config am.messageid true
+	$ cat >.git/hooks/applypatch-msg <<'EOF'
+	#!/bin/sh
+	. git-sh-setup
+	perl -pi -e 's|^Message-Id:\s*<?([^>]+)>?$|Link: https://lore.kernel.org/r/$1|g;' "$1"
+	test -x "$GIT_DIR/hooks/commit-msg" &&
+		exec "$GIT_DIR/hooks/commit-msg" ${1+"$@"}
+	:
+	EOF
+	$ chmod a+x .git/hooks/applypatch-msg
diff --git a/Documentation/process/index.rst b/Documentation/process/index.rst
index e2c9ffc682c5..482b07402836 100644
--- a/Documentation/process/index.rst
+++ b/Documentation/process/index.rst
@@ -46,6 +46,7 @@ Other guides to the community that are of interest to most developers are:
    kernel-docs
    deprecated
    embargoed-hardware-issues
+   applying-patches-using-git
 
 These are some overall technical guides that have been put here for now for
 lack of a better place.
-- 
2.21.0

Re: [PATCH] Documentation: Document how to get links with git am

[Jonathan Corbet]

On Fri, 15 Nov 2019 14:30:21 +0100
Linus Walleij <linus.walleij@linaro.org> wrote:

> This adds Kees' clever apply hook to the kernel documentation so
> it can be easily references when needed.
> 
> Cc: Kees Cook <keescook@chromium.org>
> Link: https://lists.linuxfoundation.org/pipermail/ksummit-discuss/2019-July/006608.html
> Signed-off-by: Linus Walleij <linus.walleij@linaro.org>

Seems generally useful.  I have a couple of overall questions...

 - Might this be better placed in the maintainer manual?  It is more
   likely to be relevant to that audience, methinks.

 - I wonder if the hook script should just go under tools/ somewhere for
   people to grab.

Thanks,

jon

Re: [PATCH] Documentation: Document how to get links with git am

[Kees Cook]

On Fri, Nov 15, 2019 at 01:00:17PM -0700, Jonathan Corbet wrote:
> On Fri, 15 Nov 2019 14:30:21 +0100
> Linus Walleij <linus.walleij@linaro.org> wrote:
> 
> > This adds Kees' clever apply hook to the kernel documentation so
> > it can be easily references when needed.
> > 
> > Cc: Kees Cook <keescook@chromium.org>
> > Link: https://lists.linuxfoundation.org/pipermail/ksummit-discuss/2019-July/006608.html
> > Signed-off-by: Linus Walleij <linus.walleij@linaro.org>
> 
> Seems generally useful.  I have a couple of overall questions...
> 
>  - Might this be better placed in the maintainer manual?  It is more
>    likely to be relevant to that audience, methinks.

Seems reasonable.

>  - I wonder if the hook script should just go under tools/ somewhere for
>    people to grab.

Do we have anywhere to put these kinds of things, or do we need create
something new?

-- 
Kees Cook

Re: [PATCH] Documentation: Document how to get links with git am

[Linus Walleij]

On Fri, Nov 15, 2019 at 9:00 PM Jonathan Corbet <corbet@lwn.net> wrote:
> On Fri, 15 Nov 2019 14:30:21 +0100
> Linus Walleij <linus.walleij@linaro.org> wrote:
>
> > This adds Kees' clever apply hook to the kernel documentation so
> > it can be easily references when needed.
> >
> > Cc: Kees Cook <keescook@chromium.org>
> > Link: https://lists.linuxfoundation.org/pipermail/ksummit-discuss/2019-July/006608.html
> > Signed-off-by: Linus Walleij <linus.walleij@linaro.org>
>
> Seems generally useful.  I have a couple of overall questions...
>
>  - Might this be better placed in the maintainer manual?  It is more
>    likely to be relevant to that audience, methinks.

Oh that exists now, Documentation/maintainer? Sure I fix.

>  - I wonder if the hook script should just go under tools/ somewhere for
>    people to grab.

Does one exclude the other?

Can we place it under tools/scripts/git and somehow source the contents into
this file so you can also see it?

Yours,
Linus Walleij

Re: [PATCH] Documentation: Document how to get links with git am

[Jonathan Corbet]

On Fri, 15 Nov 2019 15:18:22 -0800
Kees Cook <keescook@chromium.org> wrote:

> >  - I wonder if the hook script should just go under tools/ somewhere for
> >    people to grab.  
> 
> Do we have anywhere to put these kinds of things, or do we need create
> something new?

I don't think there's a place now; I bet, though, if we were to create a
tools/git it would get other useful stuff before too long.

jon

Re: [PATCH] Documentation: Document how to get links with git am

[Jonathan Corbet]

On Sat, 16 Nov 2019 00:32:35 +0100
Linus Walleij <linus.walleij@linaro.org> wrote:

> > Seems generally useful.  I have a couple of overall questions...
> >
> >  - Might this be better placed in the maintainer manual?  It is more
> >    likely to be relevant to that audience, methinks.  
> 
> Oh that exists now, Documentation/maintainer? Sure I fix.

Indeed it exists...it's a little sparse at the moment, but that's what
I'm trying to improve...:)

> >  - I wonder if the hook script should just go under tools/ somewhere for
> >    people to grab.  
> 
> Does one exclude the other?
> 
> Can we place it under tools/scripts/git and somehow source the contents into
> this file so you can also see it?

That could be done...something like:

	.. include:: ../../scripts/git/add-link
		:literal:

should do it...obviously adjusted for the actual name and location of the
script.

Of course, cutting the script from the document isn't all that big a deal
either; that was mostly just me wondering.

Thanks,

jon