Re: [patch 2/2] Documentation/process: Add tip tree handbook

[Ingo Molnar <mingo@kernel.org>]

* Thomas Gleixner <tglx@linutronix.de> wrote:

> + - Signed-off-by: ``Patch handler <handler@mail>``
> +
> +   SOBs after the author SOB are from people handling and transporting the
> +   patch, but were not involved in development. If the handler made
> +   modifications to the patch or the changelog, then this should be
> +   mentioned **after** the changelog text and **above** all commit tags in
> +   the following format::
> +
> +     ... changelog text ends.
> +
> +     [ handler: Replaced foo by bar and updated changelog ]
> +
> +     First-tag: .....
> +
> +   Note the two empty new lines which separate the changelog text and the
> +   commit tags from that notice.

Even after a decade of introducing Git I still see Signed-off-by used as 
an Acked-by or Reviewed-by substitutes, so I'd suggest adding this small 
explanation as well:

  +   SOB chains should reflect the *real* route a patch took as it was 
  +   propagated to us, with the first SOB entry signalling primary
  +   authorship of a single author. Acks should be given as Acked-by 
  +   lines and review approvals as Reviewed-by lines.


> +   If a patch is sent to the mailing list by a handler then the author has
> +   to be noted in the first line of the changelog with::
> +
> +     From: ``Author <author@mail>``
> +
> +     Changelog text starts here....
> +
> +   so the authorship is preserved. The 'From:' line has to be followed by a
> +   empty newline. If that 'From:' line is missing, then the patch would be
> +   attributed to the person who sent (transported) it. The 'From:' line is
> +   automatically removed when the patch is applied and does not show up in
> +   the final git changelog. It merely affects the authorship information of
> +   the resulting git commit.

s/(transported)
 /(transported, handled)

to connect the text with the whole 'handler' language used before?

and since we are not talking about the 'git command', maybe also:

s/git
 /Git

?

> + - Cc: ``cc-ed-person <person@mail>``
> +
> +   If the patch should be backported to stable, then please add a '``Cc:
> +   stable@vger.kernel.org``' tag, but do not Cc stable when sending your
> +   mail.

Can I suggest a more canonical form:

	Cc: <stable@vger.kernel.org> # v4.18 and later kernels

It would be nice if people adding Cc: stable lines would actually try to 
figure out which exact kernel versions are affected.

Also the '<>' form makes it easier to read and my email client will also 
syntax highlight it in that case. ;-)


> + - Link: ``https://link/to/information``
> +
> +   For referring to email on LKML or other kernel mailing lists, please use
> +   the lkml.kernel.org redirector URL::

s/referring to email
 /referring to an email

> +
> +     https://lkml.kernel.org/r/email-message@id
> +
> +   The kernel.org redirector is considered a stable URL unlike other email
> +   archives.

s/URL unlike
 /URL, unlike

?

Thanks,

	Ingo