Re: [GIT PULL] Please pull IOMMUFD subsystem changes

[Linus Torvalds]

On Fri, Feb 24, 2023 at 4:02 PM Jason Gunthorpe <jgg@xxxxxxxxxx> wrote:
>
> Do you like this sort of explanation in the email or the tag?

Either works, I really don't have a strong preference. Some people do
one, others do the other. And some people (like Rafael) do both - with
the summary list in the tag (and thus also as part of the pull
request), but an overview at the top of the email.

> Honestly, after 5 years (wow time flies) of sending PRs for rdma I'm
> still a bit unclear on the best way to write the tag message.

Heh. Probably because there isn't any "one correct" way. Whatever
works best for you.

The thing I personally care about is just that there _is_ an
explanation, and that it makes sense in the context of a human reader
who looks at the merge later.

So no automatically generated stuff that you could just get with some
git command anyway, but an actual overview.

And I'll edit things to make sense in a commit message anyway, so I'll
remove language like "This pull request contains.." because that
doesn't make sense once it's just a merge commit and no longer is a
pull request.

So I'll generally edit that kind of laniage down to "This contains.."
instead or something like that.

I also try to *generally* make the merge commit messages look roughly
the same, so that when people use wildly different whitespace (tabs vs
spaces) or use different bullet points - "-" vs "o" vs "*" etc) I
generally try to make those kinds of things also be at least
*somewhat* consistent.

And for that, it can certainly make my life easier if you look at what
merge messages look like, and don't try to make your pull request
message wildly different. But it's really not a big deal - I do that
kind of reformatting as part of simply reading the message, so it's
all fine.

Finally - remember that the merge message is for humans reading it
later, and not everybody necessarily knows the TLA's that may be
obvious to you as a maintainer of that subsystem. So try to make it
somewhat legible to a general (kernel developer) public.

And then if I feel like the message doesn't cover all of the changes,
I'll prod you, like I did in this case.

               Linus