Re: [GIT] Networking

[Linus Torvalds]

On Mon, Sep 21, 2020 at 6:44 PM Jakub Kicinski <kuba@xxxxxxxxxx> wrote:
>
> Here are the latest updates from the networking tree:

Pulled.

But I'd ask for a couple of things for future pull requests:

 (a) please put "git pull" somewhere in the email (lots of people just
put it in the subject by prepending it with "[GIT PULL]" but all I
really look for is "git" and "pull" anywhere in the email. You had the
"git" but there was no "pull" anywhere).

This can be as simple as just adding a "Please pull" or something.
Anything to trigger my search terms. Otherwise the pull request
doesn't show up when I start doing pulls - I'll see it eventually, but
it might end up delayed.

 (b) please use an imperative sentence structure for the description
instead of present tense.

The end result reads _much_ better when you look at the end result
after the fact. Just as an example:

> Ido fixes failure to add bond interfaces to a bridge, the offload-handling
> code was too defensive there and recent refactoring unearthed that.
> Users complained.

Instead of "Ido fixes failure", please just say "Fix failure".

We actually have this in our "Submitting Patches" documentation, for
the patch descriptions, but it holds for pull request descriptions
too, for all the same reasons. There the example is

  Describe your changes in imperative mood, e.g. "make xyzzy do frotz"
  instead of "[This patch] makes xyzzy do frotz" or "[I] changed xyzzy
  to do frotz", as if you are giving orders to the codebase to change
  its behaviour.

but the issue is kind of the same. Using present tense in particular
is very odd when somebody fixed something a year ago and you go back
to the description that says "Ido fixes". No, he fixed things long
ago.

I basically try to make the commit logs be _roughly_ similar (well,
there's basically two kinds of logs: the freeform descriptive ones,
and the ones that are a list of changes and use bullet points - and
then you have the ones that do both). That also involves primarily
just describing the _fixes_ (and possibly the problems). Giving credit
to the developers is obviously fine, but if you want to call out the
developer, please do it _after_ describing the actual fix. Because the
commit log (whether for an individual patch or for a merge message) is
primarily about what the change is about. Authorship is separate (and
generally shows up as such).

End result: I rewrote the above wording into

 - fix failure to add bond interfaces to a bridge, the offload-handling
   code was too defensive there and recent refactoring unearthed that.
   Users complained (Ido)

and that's basically would be the form I'd prefer things to be in.

Also, I'd love to see signed tags. I don't _require_ them for
git.kernel.org pulls, but I do prefer them.

Thanks,

           Linus