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

Ingo Molnar
2018-11-08T07:40:21Z

* 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