Re: RFC tips-for-maintainers.txt (was Re: [GIT PULL] platform-drivers-x86 for 4.6-3)

2016-04-28 Thread Darren Hart 
On Thu, Apr 28, 2016 at 02:25:00PM +1000, Michael Ellerman wrote:
> On Wed, 2016-04-27 at 09:57 -0700, Darren Hart wrote:
> > On Wed, Apr 27, 2016 at 09:08:01AM -0700, Linus Torvalds wrote:
> > > On Tue, Apr 26, 2016 at 10:02 PM, Darren Hart  
> > > wrote:
> > > >
> > > > Found myself not wanting to send a one patch pull request, but not 
> > > > wanting to
> > > > wait until RC6 and possibly miss 4.6.
> > > >
> > > > Do you have a preference during the RC cycle in terms of balance 
> > > > between patch
> > > > count and frequency for a small subsystem like platform-driver-x86?
> > >
> > > Once a week like this is fine, even if it's just a single trivial
> > > one-liner change.
> ...
> 
> > Very helpful, thank you Linus. I believe I just inherited a TODO to find the
> > right spot in the documentation to record this.
> 
> Actually I've been meaning to do that for ages, and I have a few more 
> collected
> in my notes.
> 
> How do these look?
> 

Wow, thanks for doing this!

> 
>   Git pulls should start "[GIT PULL]":
> 
>   
> http://lkml.kernel.org/r/CA+55aFxURVwV4NZcPsVzQ-Ui9Nmn2vdXVw==s5rkhxc1y4b...@mail.gmail.com
> 
>just for your information: this pull request doesn't show up with my
>   normal merge-window search pattern of "git pull", because you never
>   actually say "pull" anywhere.
> 
>   Please use a subject with "[GIT PULL]" prefix (preferred), or just
>   change the body of the email to have a "please pull" in it or
>   something.  I get too much email, and particularly during the merge
>   window it really helps if I can keep my pull emails separate from
>   other stuff by just having them match a simple pattern.

I would suggest we extract and consolidate the direction we receive from Linus
and write it up in our own words, rather than using quotes and having the reader
piece them together.

Linus has said he does not like to be prescriptive, he'd rather say "don't do
this" than "everyone must do this". However, I think our documentation should
include guidelines and known good methods. So for this subject, perhaps:

--
Git pull requests should include the "[GIT PULL]" prefix in the subject and
contains "please pull" somewhere in the body. The "git request-pull" command
will generate an acceptable email message body.

http://lkml.kernel.org/r/CA+55aFxURVwV4NZcPsVzQ-Ui9Nmn2vdXVw==s5rkhxc1y4b...@mail.gmail.com
--

In my opinion, this tool should be more robust and generate the full email body
using parameters, which is why I (and many other maintainers) use wrapper
scripts. We could include an example here, but that's probably best left to some
kind of a tooling repository or updates to git itself.

> 
> 
>   Linus generally likes to see merge conflicts himself, for subtle conflicts
>   you can provide a separate tree with the result of your merge:
> 
>   
> http://lkml.kernel.org/r/ca+55afwm2e9stvtyjrnpjh5rszafbxbj5ffykyi730ojon+...@mail.gmail.com
> 
>   On Sat, Sep 5, 2015 at 2:37 AM, Neil Brown  wrote:
>   >
>   > Please pull these updates.  I've already merged with the 'block' tree
>   > to resolve a few simple conflicts.
> 
>   So for the future, I actually prefer to see and handle the conflicts 
> myself.
> 
>   I really just prefer knowing what's going on, and merge conflicts are
>   an indication of cross-maintainer issues which are *exactly* the kinds
>   of things I want to be aware of.
> 
>   However, in this case I was "ok, I've already done several other merge
>   resolutions with the wbole damn bio_endio error handling changes", so
>   I felt I was aware enough about how that ended up being a
>   cross-subsystem conflict, and just took your pre-merged version.
> 
>   If you feel that the conflicts are particularly subtle, or just
>   generally worry about the merge, or just because you want to do some
>   merge-testing, what some people end up doing is to send me their
>   unmerged branch, and then send me a separate ".. and here's the merge
>   I did". I'll then do the merge myself anyway, but then after doing the
>   merge I'll switch to a temporary testing branch and re-do the  merge
>   with the pre-merged state just to verify. Generally the end result is
>   identical, but when it isn't, that's actually usually interesting
>   (sometimes it's just a ordering difference, but sometimes it's a merge
>   error - and so far I think most merge errors have come from
>   sub-maintainers, for the simple reason that they generally aren't as
>   used to merging as I am - so even if they know the code better, I
>   sometimes catch merge gotcha's better).
> 

Similar comments for this one. Also s/tree/branch/

All the above really can be condensed into something like this:

--
Send your pull requests based off the Linux master branch and leave the merging
to Linus as he prefers to see the conflicts. If

Re: RFC tips-for-maintainers.txt (was Re: [GIT PULL] platform-drivers-x86 for 4.6-3)

2016-04-28 Thread Darren Hart 
On Thu, Apr 28, 2016 at 02:25:00PM +1000, Michael Ellerman wrote:
> On Wed, 2016-04-27 at 09:57 -0700, Darren Hart wrote:
> > On Wed, Apr 27, 2016 at 09:08:01AM -0700, Linus Torvalds wrote:
> > > On Tue, Apr 26, 2016 at 10:02 PM, Darren Hart  
> > > wrote:
> > > >
> > > > Found myself not wanting to send a one patch pull request, but not 
> > > > wanting to
> > > > wait until RC6 and possibly miss 4.6.
> > > >
> > > > Do you have a preference during the RC cycle in terms of balance 
> > > > between patch
> > > > count and frequency for a small subsystem like platform-driver-x86?
> > >
> > > Once a week like this is fine, even if it's just a single trivial
> > > one-liner change.
> ...
> 
> > Very helpful, thank you Linus. I believe I just inherited a TODO to find the
> > right spot in the documentation to record this.
> 
> Actually I've been meaning to do that for ages, and I have a few more 
> collected
> in my notes.
> 
> How do these look?
> 

Wow, thanks for doing this!

> 
>   Git pulls should start "[GIT PULL]":
> 
>   
> http://lkml.kernel.org/r/CA+55aFxURVwV4NZcPsVzQ-Ui9Nmn2vdXVw==s5rkhxc1y4b...@mail.gmail.com
> 
>just for your information: this pull request doesn't show up with my
>   normal merge-window search pattern of "git pull", because you never
>   actually say "pull" anywhere.
> 
>   Please use a subject with "[GIT PULL]" prefix (preferred), or just
>   change the body of the email to have a "please pull" in it or
>   something.  I get too much email, and particularly during the merge
>   window it really helps if I can keep my pull emails separate from
>   other stuff by just having them match a simple pattern.

I would suggest we extract and consolidate the direction we receive from Linus
and write it up in our own words, rather than using quotes and having the reader
piece them together.

Linus has said he does not like to be prescriptive, he'd rather say "don't do
this" than "everyone must do this". However, I think our documentation should
include guidelines and known good methods. So for this subject, perhaps:

--
Git pull requests should include the "[GIT PULL]" prefix in the subject and
contains "please pull" somewhere in the body. The "git request-pull" command
will generate an acceptable email message body.

http://lkml.kernel.org/r/CA+55aFxURVwV4NZcPsVzQ-Ui9Nmn2vdXVw==s5rkhxc1y4b...@mail.gmail.com
--

In my opinion, this tool should be more robust and generate the full email body
using parameters, which is why I (and many other maintainers) use wrapper
scripts. We could include an example here, but that's probably best left to some
kind of a tooling repository or updates to git itself.

> 
> 
>   Linus generally likes to see merge conflicts himself, for subtle conflicts
>   you can provide a separate tree with the result of your merge:
> 
>   
> http://lkml.kernel.org/r/ca+55afwm2e9stvtyjrnpjh5rszafbxbj5ffykyi730ojon+...@mail.gmail.com
> 
>   On Sat, Sep 5, 2015 at 2:37 AM, Neil Brown  wrote:
>   >
>   > Please pull these updates.  I've already merged with the 'block' tree
>   > to resolve a few simple conflicts.
> 
>   So for the future, I actually prefer to see and handle the conflicts 
> myself.
> 
>   I really just prefer knowing what's going on, and merge conflicts are
>   an indication of cross-maintainer issues which are *exactly* the kinds
>   of things I want to be aware of.
> 
>   However, in this case I was "ok, I've already done several other merge
>   resolutions with the wbole damn bio_endio error handling changes", so
>   I felt I was aware enough about how that ended up being a
>   cross-subsystem conflict, and just took your pre-merged version.
> 
>   If you feel that the conflicts are particularly subtle, or just
>   generally worry about the merge, or just because you want to do some
>   merge-testing, what some people end up doing is to send me their
>   unmerged branch, and then send me a separate ".. and here's the merge
>   I did". I'll then do the merge myself anyway, but then after doing the
>   merge I'll switch to a temporary testing branch and re-do the  merge
>   with the pre-merged state just to verify. Generally the end result is
>   identical, but when it isn't, that's actually usually interesting
>   (sometimes it's just a ordering difference, but sometimes it's a merge
>   error - and so far I think most merge errors have come from
>   sub-maintainers, for the simple reason that they generally aren't as
>   used to merging as I am - so even if they know the code better, I
>   sometimes catch merge gotcha's better).
> 

Similar comments for this one. Also s/tree/branch/

All the above really can be condensed into something like this:

--
Send your pull requests based off the Linux master branch and leave the merging
to Linus as he prefers to see the conflicts. If the merge is complex, or
contains some

RFC tips-for-maintainers.txt (was Re: [GIT PULL] platform-drivers-x86 for 4.6-3)

2016-04-27 Thread Michael Ellerman 
On Wed, 2016-04-27 at 09:57 -0700, Darren Hart wrote:
> On Wed, Apr 27, 2016 at 09:08:01AM -0700, Linus Torvalds wrote:
> > On Tue, Apr 26, 2016 at 10:02 PM, Darren Hart  wrote:
> > >
> > > Found myself not wanting to send a one patch pull request, but not 
> > > wanting to
> > > wait until RC6 and possibly miss 4.6.
> > >
> > > Do you have a preference during the RC cycle in terms of balance between 
> > > patch
> > > count and frequency for a small subsystem like platform-driver-x86?
> >
> > Once a week like this is fine, even if it's just a single trivial
> > one-liner change.
...

> Very helpful, thank you Linus. I believe I just inherited a TODO to find the
> right spot in the documentation to record this.

Actually I've been meaning to do that for ages, and I have a few more collected
in my notes.

How do these look?


  Git pulls should start "[GIT PULL]":

  
http://lkml.kernel.org/r/CA+55aFxURVwV4NZcPsVzQ-Ui9Nmn2vdXVw==s5rkhxc1y4b...@mail.gmail.com

   just for your information: this pull request doesn't show up with my
  normal merge-window search pattern of "git pull", because you never
  actually say "pull" anywhere.

  Please use a subject with "[GIT PULL]" prefix (preferred), or just
  change the body of the email to have a "please pull" in it or
  something.  I get too much email, and particularly during the merge
  window it really helps if I can keep my pull emails separate from
  other stuff by just having them match a simple pattern.


  Linus generally likes to see merge conflicts himself, for subtle conflicts
  you can provide a separate tree with the result of your merge:

  
http://lkml.kernel.org/r/ca+55afwm2e9stvtyjrnpjh5rszafbxbj5ffykyi730ojon+...@mail.gmail.com

  On Sat, Sep 5, 2015 at 2:37 AM, Neil Brown  wrote:
  >
  > Please pull these updates.  I've already merged with the 'block' tree
  > to resolve a few simple conflicts.

  So for the future, I actually prefer to see and handle the conflicts 
myself.

  I really just prefer knowing what's going on, and merge conflicts are
  an indication of cross-maintainer issues which are *exactly* the kinds
  of things I want to be aware of.

  However, in this case I was "ok, I've already done several other merge
  resolutions with the wbole damn bio_endio error handling changes", so
  I felt I was aware enough about how that ended up being a
  cross-subsystem conflict, and just took your pre-merged version.

  If you feel that the conflicts are particularly subtle, or just
  generally worry about the merge, or just because you want to do some
  merge-testing, what some people end up doing is to send me their
  unmerged branch, and then send me a separate ".. and here's the merge
  I did". I'll then do the merge myself anyway, but then after doing the
  merge I'll switch to a temporary testing branch and re-do the  merge
  with the pre-merged state just to verify. Generally the end result is
  identical, but when it isn't, that's actually usually interesting
  (sometimes it's just a ordering difference, but sometimes it's a merge
  error - and so far I think most merge errors have come from
  sub-maintainers, for the simple reason that they generally aren't as
  used to merging as I am - so even if they know the code better, I
  sometimes catch merge gotcha's better).

  Don't rebase your tree between linux-next and requesting a pull unless you
  absolutely must:

  
http://lkml.kernel.org/r/CA+55aFyrep8hMApzYA4DyFgEoHc8o8KATTV=jqf6-fgtlsq...@mail.gmail.com

  Just stop [rebasing]. I'll handle the merge issues. If there are
  complicated merge problems that you really worry about, what you can do
  is

   (a) make a test-merge just to check

   (b) do NOT send me that test-merge

   (c) as part of the pull request, tell me that "there's a conflict
  because xyz, and this is how we think it should be handled".

  ...

  There are valid reasons to rebase, but those are along the line of "we
  messed up catastrophically, and we _have_ to clean up the history".

  A simple merge conflict due to a trivial duplicated commit is not a 
reason.

  Linus likes signed tags with a short blurb:

  
http://lkml.kernel.org/r/CA+55aFwa9b5=aykxnkfcaqn27pfy8gchuhck+pkrqcfgn6f...@mail.gmail.com

  .. the above is a tag, but it's not signed, nor even annotated. So it
  has no message about what the fixes are in it, it's just the plain
  SHA1 id.

  Now, I don't really require signed tags from kernel.org, but it would
  still be nice. And I *do* want a little blurb about the fixes, even if
  it doesn't have to be all that exhaustive. Putting that in the tag is
  convenient, but I'm ok with it being just in the email message too,
  like you usually do.

  Linus really wants signed tags when

RFC tips-for-maintainers.txt (was Re: [GIT PULL] platform-drivers-x86 for 4.6-3)

2016-04-27 Thread Michael Ellerman 
On Wed, 2016-04-27 at 09:57 -0700, Darren Hart wrote:
> On Wed, Apr 27, 2016 at 09:08:01AM -0700, Linus Torvalds wrote:
> > On Tue, Apr 26, 2016 at 10:02 PM, Darren Hart  wrote:
> > >
> > > Found myself not wanting to send a one patch pull request, but not 
> > > wanting to
> > > wait until RC6 and possibly miss 4.6.
> > >
> > > Do you have a preference during the RC cycle in terms of balance between 
> > > patch
> > > count and frequency for a small subsystem like platform-driver-x86?
> >
> > Once a week like this is fine, even if it's just a single trivial
> > one-liner change.
...

> Very helpful, thank you Linus. I believe I just inherited a TODO to find the
> right spot in the documentation to record this.

Actually I've been meaning to do that for ages, and I have a few more collected
in my notes.

How do these look?


  Git pulls should start "[GIT PULL]":

  
http://lkml.kernel.org/r/CA+55aFxURVwV4NZcPsVzQ-Ui9Nmn2vdXVw==s5rkhxc1y4b...@mail.gmail.com

   just for your information: this pull request doesn't show up with my
  normal merge-window search pattern of "git pull", because you never
  actually say "pull" anywhere.

  Please use a subject with "[GIT PULL]" prefix (preferred), or just
  change the body of the email to have a "please pull" in it or
  something.  I get too much email, and particularly during the merge
  window it really helps if I can keep my pull emails separate from
  other stuff by just having them match a simple pattern.


  Linus generally likes to see merge conflicts himself, for subtle conflicts
  you can provide a separate tree with the result of your merge:

  
http://lkml.kernel.org/r/ca+55afwm2e9stvtyjrnpjh5rszafbxbj5ffykyi730ojon+...@mail.gmail.com

  On Sat, Sep 5, 2015 at 2:37 AM, Neil Brown  wrote:
  >
  > Please pull these updates.  I've already merged with the 'block' tree
  > to resolve a few simple conflicts.

  So for the future, I actually prefer to see and handle the conflicts 
myself.

  I really just prefer knowing what's going on, and merge conflicts are
  an indication of cross-maintainer issues which are *exactly* the kinds
  of things I want to be aware of.

  However, in this case I was "ok, I've already done several other merge
  resolutions with the wbole damn bio_endio error handling changes", so
  I felt I was aware enough about how that ended up being a
  cross-subsystem conflict, and just took your pre-merged version.

  If you feel that the conflicts are particularly subtle, or just
  generally worry about the merge, or just because you want to do some
  merge-testing, what some people end up doing is to send me their
  unmerged branch, and then send me a separate ".. and here's the merge
  I did". I'll then do the merge myself anyway, but then after doing the
  merge I'll switch to a temporary testing branch and re-do the  merge
  with the pre-merged state just to verify. Generally the end result is
  identical, but when it isn't, that's actually usually interesting
  (sometimes it's just a ordering difference, but sometimes it's a merge
  error - and so far I think most merge errors have come from
  sub-maintainers, for the simple reason that they generally aren't as
  used to merging as I am - so even if they know the code better, I
  sometimes catch merge gotcha's better).

  Don't rebase your tree between linux-next and requesting a pull unless you
  absolutely must:

  
http://lkml.kernel.org/r/CA+55aFyrep8hMApzYA4DyFgEoHc8o8KATTV=jqf6-fgtlsq...@mail.gmail.com

  Just stop [rebasing]. I'll handle the merge issues. If there are
  complicated merge problems that you really worry about, what you can do
  is

   (a) make a test-merge just to check

   (b) do NOT send me that test-merge

   (c) as part of the pull request, tell me that "there's a conflict
  because xyz, and this is how we think it should be handled".

  ...

  There are valid reasons to rebase, but those are along the line of "we
  messed up catastrophically, and we _have_ to clean up the history".

  A simple merge conflict due to a trivial duplicated commit is not a 
reason.

  Linus likes signed tags with a short blurb:

  
http://lkml.kernel.org/r/CA+55aFwa9b5=aykxnkfcaqn27pfy8gchuhck+pkrqcfgn6f...@mail.gmail.com

  .. the above is a tag, but it's not signed, nor even annotated. So it
  has no message about what the fixes are in it, it's just the plain
  SHA1 id.

  Now, I don't really require signed tags from kernel.org, but it would
  still be nice. And I *do* want a little blurb about the fixes, even if
  it doesn't have to be all that exhaustive. Putting that in the tag is
  convenient, but I'm ok with it being just in the email message too,
  like you usually do.

  Linus really wants signed tags when pulling from non-kernel.org, even if your